Metabase için resmi MCP sunucusu; veri arama, anlamsal katmanda sorgular oluşturma ve MCP istemcileri aracılığıyla sonuçları görselleştirme işlevlerini sağlar.
Neler yapabilirsiniz?
- Metabase içeriğini arayın — Anahtar kelimeler veya doğal dil sorguları kullanarak tabloları, metrikleri, kartları, panoları ve koleksiyonları search ile bulun.
- Varlıklarda gezinin ve inceleyin — Veritabanları, şemalar, tablolar, sorular, panolar ve metrikler için meta verileri metabase:// URI'leri ile read_resource aracılığıyla okuyun.
- Sorgular oluşturun ve çalıştırın — Bir tablo veya metrik üzerinde construct_query ile bir sorgu oluşturun, ardından sonuçları ve sütun meta verilerini almak için execute_query ile çalıştırın.
- Ham SQL çalıştırın — Bir veritabanına karşı yerel bir SQL sorgusunu execute_sql kullanarak çalıştırın (yerel sorgu izni ve örnek ayarının etkinleştirilmesi gerekir).
- Soruları kaydedin ve güncelleyin — Oluşturulan sorgulardan kaydedilmiş soruları (kartları) create_question ve update_question kullanarak oluşturun veya değiştirin; taşıma veya arşivleme dahil.
- Panolar oluşturun ve yönetin — Otomatik konumlandırılmış kaydedilmiş sorularla yeni panoları create_dashboard ile oluşturun ve meta verilerini güncelleyin veya update_dashboard ile arşivleyin.
Metabase MCP Sunucusu
Metabase, AI istemcilerinin doğrudan bir Metabase örneğine bağlanmasını sağlayan yerleşik bir Model Bağlam Protokolü (MCP) sunucusu içerir. https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http kullanır ve arama, gezinme, sorgulama, görselleştirme ve içerik oluşturma/güncelleme araçlarını – tümü bağlanan kullanıcının izinleriyle sınırlı olarak – sunmak için Metabase'in Ajan API'si üzerine inşa edilmiştir.
Uç Nokta
MCP sunucusu şu adreste mevcuttur:
https://{your-metabase.example.com}/api/metabase-mcp
Eski /api/mcp yolu mevcut istemciler için bir takma ad olarak çalışmaya devam eder, ancak /api/metabase-mcp duyurulacak standart URL'dir.
İstemci Bağlama
Herhangi bir MCP uyumlu istemciyi /api/metabase-mcp uç noktasına yönlendirin. Örneğin, Claude Code ile:
claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http
Claude Desktop için, aynı URL'yi kullanarak bir özel bağlayıcı oluşturun.
Cursor için, Ayarlar > MCP'yi açın ve türü streamable-http ve URL'si şu olan yeni bir sunucu ekleyin:
https://{your-metabase.example.com}/api/metabase-mcp
Kimlik Doğrulama
MCP istemcileri OAuth 2.0 ile kimlik doğrular. Metabase kendi gömülü OAuth sunucusunu çalıştırır – harici bir sağlayıcıya gerek yoktur.
İlk bağlantı için akış:
- İstemci, Metabase'in OAuth uç noktalarını keşfeder.
- İstemci kendini Metabase'e kaydeder.
- Kullanıcı, oturum açmak ve bağlantıyı onaylamak için Metabase'e yönlendirilir.
- İstemci, kullanıcının Metabase izinleriyle sınırlı bir erişim belirteci alır.
Tarayıcı tabanlı oturumlar (çerez kimlik doğrulaması) da desteklenir ve kısıtlanmamış kapsamlar alır.
Kapsamlar
Erişim belirteçleri, bir istemcinin hangi araçları kullanabileceğini sınırlamak için kapsamlandırılır:
| Kapsam | Erişim izni verir |
|---|---|
agent:search |
search |
agent:resource:read |
read_resource (her zaman kimliği doğrulanmış herhangi bir çağrıcıya verilir; URI başına izin kontrolleri dağıtıcı içinde gerçekleşir) |
agent:query:construct |
construct_query |
agent:query |
query |
agent:query:execute |
execute_query |
agent:sql:construct |
construct_native_query |
agent:sql:execute |
execute_sql |
agent:question:create |
create_question |
agent:question:update |
update_question (ayrıca "kartı koleksiyona taşıma" ve arşivlemeyi de kapsar) |
agent:question:execute |
execute_question |
agent:metric:create |
create_metric |
agent:metric:update |
update_metric (ayrıca "metriği koleksiyona taşıma" ve arşivlemeyi de kapsar) |
agent:dashboard:create |
create_dashboard |
agent:dashboard:update |
update_dashboard (ayrıca arşivlemeyi de kapsar) |
agent:collection:create |
create_collection |
Joker karakter desenleri (örn. agent:*) bu ön eke sahip herhangi bir kapsamla eşleşir.
OAuth korumalı kaynak meta verileri şu adreste mevcuttur:
/.well-known/oauth-protected-resource/api/metabase-mcp
Varsayılan olarak onay ekranımız, özelleştirme fırsatı olmadan tüm kapsamlara erişim izni verir.
Mevcut Araçlar
MCP sunucusu, Ajan API uç noktası meta verilerinden dinamik olarak oluşturulan şu araçları sunar:
Keşif + okuma
| Araç | Açıklama |
|---|---|
search |
Anahtar kelime veya doğal dil sorguları kullanarak tabloları, metrikleri, kartları, panoları ve koleksiyonları arayın. |
read_resource |
metabase:// URI'sine göre bir veya daha fazla Metabase varlığını okuyun. Veritabanı/şema/tablo/koleksiyon/soru/pano/metrik/dönüşüm gezinmesini kapsar. Çağrı başına en fazla 5 URI. |
Sorgu oluşturma + yürütme
| Araç | Açıklama |
|---|---|
construct_query |
Bir tablo veya metriğe karşı bir sorgu oluşturun. Mevcut olduğunda kullanıcının orijinal prompt'ini kabul eder. execute_query veya visualize_query ile kullanılmak üzere opak bir query_handle döndürür. |
construct_native_query |
Bir veritabanı için yerel (ham SQL) bir sorgu oluşturun. create_question'i beslemek ve kaydetmek için opak bir query_handle döndürür. SQL'i yürütmez; yerel tanıtıcılar execute_query/query tarafından reddedilir (ham SQL çalıştırmak için execute_sql kullanın). |
query |
Bir tablo veya metriği doğrudan sorgulayın. Devam belirteçleri aracılığıyla sayfalamayı destekler. |
execute_query |
Daha önce oluşturulmuş bir sorguyu yürütün ve sütun meta verileriyle sonuçları döndürün. |
execute_sql |
Bir veritabanına karşı ham bir SQL sorgusu yürütün. Kullanıcının hedef veritabanında yerel sorgu iznine sahip olmasını gerektirir. mcp-execute-sql-enabled ayarı aracılığıyla örnek genelinde devre dışı bırakılabilir. |
execute_question |
Kimliğe göre kaydedilmiş bir soruyu çalıştırın ve satırlarını + sütun meta verilerini döndürün. Çağrıcının izinleri altında çalışır. Parametreli sorular desteklenmez (bir hata döndürür). |
Yazma
| Araç | Açıklama |
|---|---|
create_metric |
Bir sorguyu yeniden kullanılabilir bir metrik olarak kaydedin. construct_query'den bir query_handle kabul eder. Sorgunun bir toplama ve en fazla bir tarih gruplamasına ihtiyacı vardır. |
update_metric |
Kaydedilmiş bir metriği güncelleyin. Yama semantiği. collection_id ayarlamak onu taşır; archived: true ayarlamak onu arşivler — bir metriği silmesi istendiğinde kullanılan, geri döndürülebilir bir geçici silme. Bir yedek query hala geçerli bir metrik olmalıdır. |
create_question |
Bir sorguyu adlandırılmış bir soru (kart) olarak kaydedin. construct_query (MBQL) veya construct_native_query (yerel SQL) kaynağından bir query_handle kabul eder. Yerel kaydetme, yerel sorgu VT izni gerektirir. |
update_question |
Kaydedilmiş bir soruyu güncelleyin. Yama semantiği. collection_id ayarlamak kartı taşır. archived: true ayarlamak onu arşivler — bir soruyu silmesi istendiğinde kullanılan, geri döndürülebilir bir geçici silme. Sorguyu değiştirmek bir construct_query veya construct_native_query tanıtıcısı kabul eder. |
create_dashboard |
İsteğe bağlı olarak kaydedilmiş sorularla doldurulmuş (ızgara üzerinde otomatik konumlandırılmış) yeni bir pano oluşturun. |
update_dashboard |
Bir panonun meta verilerini güncelleyin (ad, açıklama, koleksiyon, arşivlenmiş — bir panoyu silmesi istendiğinde kullanılan, geri döndürülebilir bir geçici silme). |
create_collection |
Yeni bir koleksiyon oluşturun. İsteğe bağlı olarak bir parent_collection_id altına yuvalanmış. |
Sorgu sonuçları istek başına 200 satırla sınırlıdır. Daha fazla satır mevcut olduğunda, yanıt bir sonraki sayfayı getirmek için geri iletilebilecek bir continuation_token içerir.
read_resource liste yanıtları, truncated / total sinyalleriyle 25 öğe ile sınırlıdır; daha fazlasını görmek için belirli URI'lere inin veya search aracılığıyla daraltın.
Kaynaklar
Sunucu, istemcilerin araç açıklamalarını şişirmeden URI'ye göre ek içerik getirebilmesi için MCP kaynaklarını sunar.
| Kaynak URI'si | Açıklama |
|---|---|
metabase://docs/construct-query.md |
construct_query ve query için program sözdizimi: kaynaklar, işlemler, operatör formları, çalışılmış örnekler, tuzaklar. |
Yukarıdaki read_resource aracı, Metabase varlıklarında gezinmek için ayrı bir URI şeması kullanır (metabase://question/{id}, metabase://database/{id}/tables, vb.). İki URI ad alanı bağımsızdır: metabase://docs/..., MCP resources/read aracılığıyla getirilen statik referans içeriği içindir, metabase://table/... ve arkadaşları ise read_resource aracına iletilen varlık URI'leridir.
Desteklenen JSON-RPC Yöntemleri
| Yöntem | Açıklama |
|---|---|
initialize |
MCP bağlantısını başlatın. Sunucu yeteneklerini ve bir oturum kimliği döndürür. |
notifications/initialized |
Başlatmanın tamamlandığına dair istemci bildirimi. |
tools/list |
Mevcut araçları listeleyin (belirtecin kapsamlarına göre filtrelenmiş). |
tools/call |
Argümanlarla bir araç çağırın. |
resources/list |
Mevcut kaynakları listeleyin (belirtecin kapsamlarına göre filtrelenmiş). |
resources/read |
URI'ye göre bir kaynak okuyun. Başlatılmış bir oturum gerektirir. |
ping |
Canlı tutma pingi. |
İstekler tek tek veya bir JSON-RPC yığını olarak gönderilebilir. Sunucu, Accept başlığına bağlı olarak JSON veya SSE ile yanıt verir.
Mimari
Uygulama şu dosyalarda bulunur:
-
api.clj– HTTP işleyicisi. JSON-RPC isteklerini ayrıştırır, kimlik doğrulama ve oturum başlıklarını doğrular, kaynak kontrollerini (DNS yeniden bağlama koruması) uygular ve uygun yönteme yönlendirir. Hem JSON hem de SSE yanıt formatlarını destekler. -
tools.clj– Araç dağıtımı ve manifesto oluşturma. Ajan API uç noktası meta verilerinden araç listesini oluşturur, kapsamları kontrol eder ve araç çağrılarını sentetik Ajan API istekleri aracılığıyla yönlendirir. -
resources.clj– MCP kaynak kaydı ve işleyicileri. URI ile anahtarlanmış (construct_queryreferansı gibi) dokümantasyon kaynaklarını,resources/listveresources/readüzerinde kapsam tabanlı erişim kontrolü ile tutar. -
scope.clj– Kapsam eşleştirme mantığı. Tam eşleşmeleri, joker karakter desenlerini ve
oturum tabanlı kimlik doğrulama için::unrestrictedsentinelini destekler.
İstek akışı
MCP client -> POST /api/metabase-mcp (JSON-RPC) -> Origin + session validation -> Auth: OAuth bearer token or browser session -> Scope check against requested tool -> Synthetic request to Agent API endpoint -> Response materialized as MCP content -> JSON or SSE back to client
Daha fazla bilgi
Kaynak: mcpservers.org