Metabase

Máy chủ Metabase MCP

Metabase bao gồm một máy chủ Model Context Protocol (MCP) tích hợp sẵn cho phép các ứng dụng AI kết nối trực tiếp đến một phiên bản Metabase. Nó sử dụng https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http và xây dựng trên Agent API của Metabase để cung cấp các công cụ tìm kiếm, điều hướng, truy vấn, trực quan hóa và tạo/cập nhật nội dung - tất cả đều được giới hạn trong phạm vi quyền của người dùng kết nối.

Điểm cuối

Máy chủ MCP khả dụng tại:

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

Đường dẫn cũ /api/mcp vẫn hoạt động như một bí danh cho các ứng dụng khách hiện có, nhưng /api/metabase-mcp là URL chính thức để quảng bá.

Kết nối ứng dụng khách

Trỏ bất kỳ ứng dụng khách tương thích MCP nào đến điểm cuối /api/metabase-mcp. Ví dụ, với Claude Code:

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

Đối với Claude Desktop, tạo một trình kết nối tùy chỉnh sử dụng cùng URL đó.

Đối với Cursor, mở Settings > MCP và thêm một máy chủ mới với loại được đặt thành streamable-http và URL:

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

Xác thực

Các ứng dụng khách MCP xác thực qua OAuth 2.0. Metabase chạy máy chủ OAuth nhúng của riêng mình - không cần nhà cung cấp bên ngoài.

Quy trình cho lần kết nối đầu tiên:

1. Ứng dụng khách khám phá các điểm cuối OAuth của Metabase.
2. Ứng dụng khách tự đăng ký với Metabase.
3. Người dùng được chuyển hướng đến Metabase để đăng nhập và phê duyệt kết nối.
4. Ứng dụng khách nhận được mã truy cập được giới hạn trong phạm vi quyền Metabase của người dùng.

Các phiên dựa trên trình duyệt (xác thực cookie) cũng được hỗ trợ và nhận phạm vi không giới hạn.

Phạm vi

Mã truy cập được giới hạn phạm vi để hạn chế những công cụ mà ứng dụng khách có thể sử dụng:

Phạm vi	Cấp quyền truy cập vào
agent:search	search
agent:resource:read	read_resource (luôn được cấp cho bất kỳ người gọi đã xác thực nào; kiểm tra quyền theo URI diễn ra bên trong bộ điều phối)
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 (cũng bao gồm "di chuyển thẻ đến bộ sưu tập" và lưu trữ)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (cũng bao gồm "di chuyển chỉ số đến bộ sưu tập" và lưu trữ)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (cũng bao gồm lưu trữ)
agent:collection:create	create_collection

Các mẫu ký tự đại diện (ví dụ: agent:*) khớp với bất kỳ phạm vi nào có tiền tố đó.

Siêu dữ liệu tài nguyên được bảo vệ OAuth khả dụng tại:

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

Theo mặc định, màn hình đồng ý của chúng tôi cấp quyền truy cập vào tất cả các phạm vi mà không có cơ hội tùy chỉnh.

Các công cụ khả dụng

Máy chủ MCP cung cấp các công cụ này, được tạo động từ siêu dữ liệu điểm cuối Agent API:

Khám phá + đọc

Công cụ	Mô tả
search	Tìm kiếm bảng, chỉ số, thẻ, bảng điều khiển và bộ sưu tập bằng từ khóa hoặc truy vấn ngôn ngữ tự nhiên.
read_resource	Đọc một hoặc nhiều thực thể Metabase bằng URI metabase://. Bao gồm điều hướng cơ sở dữ liệu/lược đồ/bảng/bộ sưu tập/câu hỏi/bảng điều khiển/chỉ số/biến đổi. Tối đa 5 URI mỗi lần gọi.

Xây dựng và thực thi truy vấn

Công cụ	Mô tả
construct_query	Xây dựng một truy vấn dựa trên bảng hoặc chỉ số. Chấp nhận prompt gốc của người dùng khi có sẵn. Trả về một query_handle không rõ ràng để sử dụng với execute_query hoặc visualize_query.
construct_native_query	Xây dựng một truy vấn gốc (SQL thô) cho cơ sở dữ liệu. Trả về một query_handle không rõ ràng để cung cấp cho create_question và lưu nó. Không thực thi SQL; các handle gốc bị từ chối bởi execute_query/query (sử dụng execute_sql để chạy SQL thô).
query	Truy vấn trực tiếp một bảng hoặc chỉ số. Hỗ trợ phân trang thông qua mã thông báo tiếp tục.
execute_query	Thực thi một truy vấn đã xây dựng trước đó và trả về kết quả với siêu dữ liệu cột.
execute_sql	Thực thi một truy vấn SQL thô dựa trên cơ sở dữ liệu. Yêu cầu người dùng có quyền truy vấn gốc trên cơ sở dữ liệu đích. Có thể bị vô hiệu hóa trên toàn bộ phiên bản thông qua cài đặt mcp-execute-sql-enabled.
execute_question	Chạy một câu hỏi đã lưu theo id và trả về các hàng + siêu dữ liệu cột của nó. Chạy dưới quyền của người gọi. Câu hỏi được tham số hóa không được hỗ trợ (trả về lỗi).

Ghi

Công cụ	Mô tả
create_metric	Lưu một truy vấn dưới dạng chỉ số có thể tái sử dụng. Chấp nhận một query_handle từ construct_query. Truy vấn cần một phép tổng hợp và tối đa một nhóm theo ngày.
update_metric	Cập nhật một chỉ số đã lưu. Ngữ nghĩa vá. Đặt collection_id sẽ di chuyển nó; đặt archived: true sẽ lưu trữ nó — một xóa mềm có thể đảo ngược, được sử dụng khi được yêu cầu xóa một chỉ số. Một query thay thế vẫn phải là một chỉ số hợp lệ.
create_question	Lưu một truy vấn dưới dạng câu hỏi được đặt tên (thẻ). Chấp nhận một query_handle từ construct_query (MBQL) hoặc construct_native_query (SQL gốc). Lưu gốc yêu cầu quyền cơ sở dữ liệu truy vấn gốc.
update_question	Cập nhật một câu hỏi đã lưu. Ngữ nghĩa vá. Đặt collection_id sẽ di chuyển thẻ. Đặt archived: true sẽ lưu trữ nó — một xóa mềm có thể đảo ngược, được sử dụng khi được yêu cầu xóa một câu hỏi. Thay thế truy vấn chấp nhận một handle construct_query hoặc construct_native_query.
create_dashboard	Tạo một bảng điều khiển mới, tùy chọn được điền sẵn các câu hỏi đã lưu (tự động định vị trên lưới).
update_dashboard	Cập nhật siêu dữ liệu của bảng điều khiển (tên, mô tả, bộ sưu tập, lưu trữ — một xóa mềm có thể đảo ngược, được sử dụng khi được yêu cầu xóa một bảng điều khiển).
create_collection	Tạo một bộ sưu tập mới. Tùy chọn lồng dưới một parent_collection_id.

Kết quả truy vấn được giới hạn ở 200 hàng mỗi yêu cầu. Khi có nhiều hàng hơn, phản hồi bao gồm một continuation_token có thể được truyền lại để tìm nạp trang tiếp theo.

Phản hồi danh sách read_resource giới hạn ở 25 mục với tín hiệu truncated / total; đi sâu vào các URI cụ thể để xem thêm, hoặc tinh chỉnh qua search.

Tài nguyên

Máy chủ cung cấp tài nguyên MCP để các ứng dụng khách có thể tìm nạp nội dung bổ sung theo URI mà không làm phình to mô tả công cụ.

URI tài nguyên	Mô tả
metabase://docs/construct-query.md	Cú pháp chương trình cho construct_query và query: nguồn, thao tác, dạng toán tử, ví dụ đã làm, cạm bẫy.

Công cụ read_resource (ở trên) sử dụng một lược đồ URI riêng biệt để điều hướng các thực thể Metabase (metabase://question/{id}, metabase://database/{id}/tables, v.v.). Hai không gian tên URI độc lập: metabase://docs/... dành cho nội dung tham khảo tĩnh được tìm nạp qua resources/read MCP, trong khi metabase://table/... và các URI tương tự là các URI thực thể được truyền cho công cụ read_resource.

Các phương thức JSON-RPC được hỗ trợ

Phương thức	Mô tả
initialize	Khởi tạo kết nối MCP. Trả về khả năng của máy chủ và ID phiên.
notifications/initialized	Thông báo từ ứng dụng khách rằng quá trình khởi tạo đã hoàn tất.
tools/list	Liệt kê các công cụ khả dụng (được lọc theo phạm vi của mã thông báo).
tools/call	Gọi một công cụ với các đối số.
resources/list	Liệt kê các tài nguyên khả dụng (được lọc theo phạm vi của mã thông báo).
resources/read	Đọc một tài nguyên theo URI. Yêu cầu một phiên đã khởi tạo.
ping	Ping giữ kết nối.

Các yêu cầu có thể được gửi riêng lẻ hoặc theo lô JSON-RPC. Máy chủ phản hồi bằng JSON hoặc SSE tùy thuộc vào tiêu đề Accept.

Kiến trúc

Việc triển khai nằm trong các tệp này:

• api.clj - Trình xử lý HTTP. Phân tích cú pháp các yêu cầu JSON-RPC, xác thực tiêu đề xác thực và phiên, thực thi kiểm tra nguồn gốc (bảo vệ chống DNS rebinding) và điều phối đến phương thức thích hợp. Hỗ trợ cả định dạng phản hồi JSON và SSE.

• tools.clj - Điều phối công cụ và tạo manifest. Xây dựng danh sách công cụ từ siêu dữ liệu điểm cuối Agent API, kiểm tra phạm vi và định tuyến các lệnh gọi công cụ thông qua các yêu cầu Agent API tổng hợp.

• resources.clj - Đăng ký tài nguyên MCP và trình xử lý. Lưu giữ các tài nguyên tài liệu (như tham chiếu construct_query) được khóa bởi URI, với kiểm soát truy cập dựa trên phạm vi trên resources/list và resources/read.

• scope.clj - Logic khớp phạm vi. Hỗ trợ khớp chính xác, mẫu ký tự đại diện và sentinel ::unrestricted cho xác thực dựa trên phiên.

Luồng yêu cầu

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

Đọc thêm

• Tài liệu người dùng MCP
• Mã nguồn Agent API
• Đặc tả Model Context Protocol