Metabase

Metabase MCP Server

Metabase มีเซิร์ฟเวอร์ Model Context Protocol (MCP) ในตัวที่อนุญาตให้ไคลเอนต์ AI เชื่อมต่อโดยตรงกับอินสแตนซ์ Metabase โดยใช้ https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http และสร้างขึ้นบน Agent API ของ Metabase เพื่อเปิดเผยเครื่องมือสำหรับการค้นหา นำทาง สอบถาม แสดงผลเป็นภาพ และสร้าง/อัปเดตเนื้อหา - ทั้งหมดนี้จำกัดขอบเขตตามสิทธิ์ของผู้ใช้ที่เชื่อมต่อ

ปลายทาง (Endpoint)

เซิร์ฟเวอร์ MCP พร้อมใช้งานที่:

https://{your-metabase.example.com}/api/metabase-mcp

เส้นทางเดิม /api/mcp ยังคงใช้งานได้เป็นนามแฝงสำหรับไคลเอนต์ที่มีอยู่ แต่ /api/metabase-mcp คือ URL หลักที่ควรประกาศใช้

การเชื่อมต่อไคลเอนต์

ชี้ไคลเอนต์ที่เข้ากันได้กับ MCP ไปที่ปลายทาง /api/metabase-mcp ตัวอย่างเช่น กับ Claude Code:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

สำหรับ Claude Desktop ให้สร้าง ตัวเชื่อมต่อแบบกำหนดเอง โดยใช้ URL เดียวกัน

สำหรับ Cursor ให้เปิด Settings > MCP และเพิ่มเซิร์ฟเวอร์ใหม่โดยตั้งค่าประเภทเป็น streamable-http และ URL:

https://{your-metabase.example.com}/api/metabase-mcp

การรับรองความถูกต้อง

ไคลเอนต์ MCP รับรองความถูกต้องผ่าน OAuth 2.0 Metabase รันเซิร์ฟเวอร์ OAuth ในตัวของตัวเอง - ไม่จำเป็นต้องมีผู้ให้บริการภายนอก

ขั้นตอนสำหรับการเชื่อมต่อครั้งแรก:

1. ไคลเอนต์ค้นพบปลายทาง OAuth ของ Metabase
2. ไคลเอนต์ลงทะเบียนตัวเองกับ Metabase
3. ผู้ใช้ถูกเปลี่ยนเส้นทางไปยัง Metabase เพื่อเข้าสู่ระบบและอนุมัติการเชื่อมต่อ
4. ไคลเอนต์ได้รับโทเค็นการเข้าถึงที่จำกัดขอบเขตตามสิทธิ์ Metabase ของผู้ใช้

เซสชันที่ใช้เบราว์เซอร์ (การรับรองความถูกต้องด้วยคุกกี้) ก็รองรับเช่นกันและได้รับขอบเขตที่ไม่จำกัด

ขอบเขต (Scopes)

โทเค็นการเข้าถึงถูกจำกัดขอบเขตเพื่อจำกัดเครื่องมือที่ไคลเอนต์สามารถใช้ได้:

ขอบเขต	ให้สิทธิ์การเข้าถึง
agent:search	search
agent:resource:read	read_resource (มอบให้กับผู้เรียกที่ผ่านการรับรองความถูกต้องเสมอ; การตรวจสอบสิทธิ์ต่อ URI จะเกิดขึ้นภายในตัวกระจายงาน)
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 (รวมถึง "ย้ายการ์ดไปยังคอลเลกชัน" และการเก็บถาวร)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (รวมถึง "ย้ายเมตริกไปยังคอลเลกชัน" และการเก็บถาวร)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (รวมถึงการเก็บถาวร)
agent:collection:create	create_collection

รูปแบบไวลด์การ์ด (เช่น agent:*) จะจับคู่กับขอบเขตใดๆ ที่มีคำนำหน้านั้น

ข้อมูลเมตาของทรัพยากรที่ได้รับการป้องกันด้วย OAuth มีอยู่ที่:

/.well-known/oauth-protected-resource/api/metabase-mcp

ตามค่าเริ่มต้น หน้าจอขอความยินยอมของเราจะให้สิทธิ์การเข้าถึงทุกขอบเขตโดยไม่มีโอกาสปรับแต่ง

เครื่องมือที่พร้อมใช้งาน

เซิร์ฟเวอร์ MCP เปิดเผยเครื่องมือเหล่านี้ ซึ่งสร้างขึ้นแบบไดนามิกจากข้อมูลเมตาของปลายทาง Agent API:

การค้นหา + การอ่าน

เครื่องมือ	คำอธิบาย
search	ค้นหาตาราง เมตริก การ์ด แดชบอร์ด และคอลเลกชันโดยใช้คำสำคัญหรือคำค้นหาภาษาธรรมชาติ
read_resource	อ่านเอนทิตี Metabase หนึ่งรายการขึ้นไปด้วย URI metabase:// ครอบคลุมการนำทางฐานข้อมูล/สคีมา/ตาราง/คอลเลกชัน/คำถาม/แดชบอร์ด/เมตริก/การแปลง สูงสุด 5 URI ต่อการเรียกหนึ่งครั้ง

การสร้างคำถาม + การดำเนินการ

เครื่องมือ	คำอธิบาย
construct_query	สร้างคำถามสำหรับตารางหรือเมตริก ยอมรับ prompt ดั้งเดิมของผู้ใช้เมื่อมี ส่งคืน query_handle แบบทึบแสงสำหรับใช้กับ execute_query หรือ visualize_query
construct_native_query	สร้างคำถามแบบเนทีฟ (SQL ดิบ) สำหรับฐานข้อมูล ส่งคืน query_handle แบบทึบแสงเพื่อป้อนให้ create_question และบันทึก ไม่ได้ดำเนินการ SQL; แฮนเดิลเนทีฟจะถูกปฏิเสธโดย execute_query/query (ใช้ execute_sql เพื่อรัน SQL ดิบ)
query	สอบถามตารางหรือเมตริกโดยตรง รองรับการแบ่งหน้าผ่านโทเค็นการดำเนินการต่อ
execute_query	ดำเนินการคำถามที่สร้างไว้ก่อนหน้านี้และส่งคืนผลลัพธ์พร้อมข้อมูลเมตาของคอลัมน์
execute_sql	ดำเนินการคำถาม SQL ดิบกับฐานข้อมูล ต้องการให้ผู้ใช้มีสิทธิ์ native-query บนฐานข้อมูลเป้าหมาย สามารถปิดใช้งานได้ทั่วทั้งอินสแตนซ์ผ่านการตั้งค่า mcp-execute-sql-enabled
execute_question	รันคำถามที่บันทึกไว้ตาม id และส่งคืนแถว + ข้อมูลเมตาของคอลัมน์ รันภายใต้สิทธิ์ของผู้เรียก ไม่รองรับคำถามที่มีพารามิเตอร์ (ส่งคืนข้อผิดพลาด)

การเขียน

เครื่องมือ	คำอธิบาย
create_metric	บันทึกคำถามเป็นเมตริกที่ใช้ซ้ำได้ ยอมรับ query_handle จาก construct_query คำถามต้องการการรวมหนึ่งรายการและการจัดกลุ่มตามวันที่อย่างมากหนึ่งรายการ
update_metric	อัปเดตเมตริกที่บันทึกไว้ ใช้ความหมายแบบแพตช์ การตั้งค่า collection_id จะย้ายมัน; การตั้งค่า archived: true จะเก็บถาวรมัน — เป็นการลบแบบซอฟต์ที่ย้อนกลับได้ ใช้เมื่อถูกขอให้ลบเมตริก query ที่ใช้แทนที่ยังคงต้องเป็นเมตริกที่ถูกต้อง
create_question	บันทึกคำถามเป็นคำถามที่มีชื่อ (การ์ด) ยอมรับ query_handle จาก construct_query (MBQL) หรือ construct_native_query (SQL ดิบ) การบันทึกแบบเนทีฟต้องการสิทธิ์ native-query ของฐานข้อมูล
update_question	อัปเดตคำถามที่บันทึกไว้ ใช้ความหมายแบบแพตช์ การตั้งค่า collection_id จะย้ายการ์ด การตั้งค่า archived: true จะเก็บถาวรมัน — เป็นการลบแบบซอฟต์ที่ย้อนกลับได้ ใช้เมื่อถูกขอให้ลบคำถาม การแทนที่คำถามยอมรับแฮนเดิล construct_query หรือ construct_native_query
create_dashboard	สร้างแดชบอร์ดใหม่ สามารถเติมคำถามที่บันทึกไว้ได้ (จัดตำแหน่งอัตโนมัติบนกริด)
update_dashboard	อัปเดตข้อมูลเมตาของแดชบอร์ด (ชื่อ คำอธิบาย คอลเลกชัน เก็บถาวร — เป็นการลบแบบซอฟต์ที่ย้อนกลับได้ ใช้เมื่อถูกขอให้ลบแดชบอร์ด)
create_collection	สร้างคอลเลกชันใหม่ สามารถซ้อนภายใต้ parent_collection_id ได้

ผลลัพธ์ของคำถามถูกจำกัดที่ 200 แถวต่อคำขอ เมื่อมีแถวมากขึ้น การตอบกลับจะรวม continuation_token ที่สามารถส่งกลับมาเพื่อดึงหน้าถัดไป

การตอบกลับรายการ read_resource จำกัดที่ 25 รายการพร้อมสัญญาณ truncated / total; เจาะลึกเข้าไปใน URI เฉพาะเพื่อดูเพิ่มเติม หรือปรับแต่งผ่าน search

ทรัพยากร

เซิร์ฟเวอร์เปิดเผย ทรัพยากร ของ MCP เพื่อให้ไคลเอนต์สามารถดึงเนื้อหาเสริมตาม URI โดยไม่ต้องเพิ่มขนาดคำอธิบายเครื่องมือ

Resource URI	คำอธิบาย
metabase://docs/construct-query.md	ไวยากรณ์ของโปรแกรมสำหรับ construct_query และ query: แหล่งที่มา การดำเนินการ รูปแบบตัวดำเนินการ ตัวอย่างการทำงาน ข้อผิดพลาดที่ควรระวัง

เครื่องมือ read_resource (ด้านบน) ใช้รูปแบบ URI ที่แยกต่างหากเพื่อนำทางเอนทิตี Metabase (metabase://question/{id}, metabase://database/{id}/tables ฯลฯ) เนมสเปซ URI ทั้งสองเป็นอิสระต่อกัน: metabase://docs/... ใช้สำหรับเนื้อหาอ้างอิงแบบคงที่ที่ดึงผ่าน resources/read ของ MCP ในขณะที่ metabase://table/... และอื่นๆ คือ URI ของเอนทิตีที่ส่งไปยังเครื่องมือ read_resource

เมธอด JSON-RPC ที่รองรับ

เมธอด	คำอธิบาย
initialize	เริ่มต้นการเชื่อมต่อ MCP ส่งคืนความสามารถของเซิร์ฟเวอร์และ ID เซสชัน
notifications/initialized	การแจ้งเตือนจากไคลเอนต์ว่าการเริ่มต้นเสร็จสมบูรณ์
tools/list	แสดงรายการเครื่องมือที่พร้อมใช้งาน (กรองตามขอบเขตของโทเค็น)
tools/call	เรียกใช้เครื่องมือพร้อมอาร์กิวเมนต์
resources/list	แสดงรายการทรัพยากรที่พร้อมใช้งาน (กรองตามขอบเขตของโทเค็น)
resources/read	อ่านทรัพยากรตาม URI ต้องการเซสชันที่เริ่มต้นแล้ว
ping	การ ping เพื่อรักษาการเชื่อมต่อ

สามารถส่งคำขอทีละรายการหรือเป็นชุด JSON-RPC เซิร์ฟเวอร์ตอบกลับด้วย JSON หรือ SSE ขึ้นอยู่กับส่วนหัว Accept

สถาปัตยกรรม

การนำไปใช้งานอยู่ในไฟล์เหล่านี้:

• api.clj - ตัวจัดการ HTTP แยกวิเคราะห์คำขอ JSON-RPC ตรวจสอบการรับรองความถูกต้องและส่วนหัวของเซสชัน บังคับใช้การตรวจสอบต้นทาง (การป้องกัน DNS rebinding) และกระจายไปยังเมธอดที่เหมาะสม รองรับทั้งรูปแบบการตอบกลับ JSON และ SSE

• tools.clj - การกระจายเครื่องมือและการสร้างรายการเครื่องมือ สร้างรายการเครื่องมือจากข้อมูลเมตาของปลายทาง Agent API ตรวจสอบขอบเขต และกำหนดเส้นทางการเรียกเครื่องมือผ่านคำขอ Agent API สังเคราะห์

• resources.clj - รีจิสทรีทรัพยากร MCP และตัวจัดการ เก็บทรัพยากรเอกสาร (เช่น ข้อมูลอ้างอิง construct_query) โดยใช้คีย์ URI พร้อมการควบคุมการเข้าถึงตามขอบเขตบน resources/list และ resources/read

• scope.clj - ตรรกะการจับคู่ขอบเขต รองรับการจับคู่แบบตรงทั้งหมด รูปแบบไวลด์การ์ด และ ::unrestricted sentinel สำหรับการตรวจสอบสิทธิ์แบบอิงเซสชัน

ขั้นตอนการร้องขอ

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

อ่านเพิ่มเติม

• เอกสารผู้ใช้ MCP
• ซอร์ส Agent API
• ข้อกำหนด Model Context Protocol