Metabase

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ış:

1. İstemci, Metabase'in OAuth uç noktalarını keşfeder.
2. İstemci kendini Metabase'e kaydeder.
3. Kullanıcı, oturum açmak ve bağlantıyı onaylamak için Metabase'e yönlendirilir.
4. İ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_query referansı gibi) dokümantasyon kaynaklarını, resources/list ve resources/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 ::unrestricted sentinelini 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

• MCP kullanıcı belgeleri
• Agent API kaynağı
• Model Context Protocol belirtimi