Skip to content
Back to search

mcp-metabase-server

A comprehensive MCP server for Metabase with 70+ tools.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/easecloudio--mcp-metabase-server/badge.svg)](/listings/easecloudio--mcp-metabase-server)

HTML

<a href="/listings/easecloudio--mcp-metabase-server"><img src="/api/listings/easecloudio--mcp-metabase-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @easecloudio/mcp-metabase-server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 469 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Metabase MCP Server
  2. [![npm version](https://img.shields.io/npm/v/@easecloudio/mcp-metabase-server)](https://www.npmjs.com/package/@easecloudio/mcp-metabase-server)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
  5. [![GitHub](https://img.shields.io/badge/GitHub-easecloudio%2Fmcp--metabase--server-blue)](https://github.com/easecloudio/mcp-metabase-server)
  6. A **Model Context Protocol (MCP) server for Metabase** that gives AI assistants full access to your analytics platform — dashboards, cards, databases, tables, collections, and more.
  7. **Developed and maintained by [EaseCloud](https://easecloud.io)** — cloud-native, AI-driven, and data infrastructure solutions.
  8. ## Quick Start
  9. ```bash
  10. export METABASE_URL=https://your-metabase-instance.com
  11. export METABASE_API_KEY=your_metabase_api_key
  12. npx @easecloudio/mcp-metabase-server
  13. ```
  14. ## 96 Tools Available
  15. | Domain | Tools |
  16. |---|---|
  17. | Dashboard Management | 27 |
  18. | Card / Question Management | 21 |
  19. | Database Management | 16 |
  20. | Table Management | 17 |
  21. | Collections, Users & Search | 13 |
  22. | Schema Cache (SQL→MBQL) | 2 |
  23. ## Supported Metabase Versions
  24. - Metabase v0.46.x and above (recommended: v0.48.x or later)
  25. - Metabase Cloud (fully supported)
  26. - Self-hosted instances (Docker, JAR, or cloud deployments)
  27. ## Installation
  28. ### npx (Recommended)
  29. ```bash
  30. npx @easecloudio/mcp-metabase-server
  31. ```
  32. ### Global install
  33. ```bash
  34. npm install -g @easecloudio/mcp-metabase-server
  35. mcp-metabase-server
  36. ```
  37. ### Docker
  38. ```bash
  39. docker build -t mcp-metabase-server .
  40. docker run -it --rm \
  41. -e METABASE_URL=https://your-metabase-instance.com \
  42. -e METABASE_API_KEY=your_metabase_api_key \
  43. mcp-metabase-server
  44. ```
  45. ## Configuration
  46. ### Authentication
  47. **API Key (preferred):**
  48. ```bash
  49. METABASE_URL=https://your-metabase-instance.com
  50. METABASE_API_KEY=your_metabase_api_key
  51. ```
  52. **Username / Password (fallback):**
  53. ```bash
  54. METABASE_URL=https://your-metabase-instance.com
  55. METABASE_USERNAME=your_username
  56. METABASE_PASSWORD=your_password
  57. ```
  58. Copy `.env.example` to `.env` and fill in your values.
  59. ### Tool Filtering (TOOL_MODE)
  60. Set `TOOL_MODE` to control which tools are exposed to the AI. Useful for limiting surface area or preventing accidental writes.
  61. | Mode | Description |
  62. |---|---|
  63. | `all` | Every available tool (default) |
  64. | `essential` | Core read + execute tools only |
  65. | `read` | All non-destructive tools |
  66. | `write` | All tools including create / update / delete |
  67. ```bash
  68. TOOL_MODE=essential # smallest surface area
  69. TOOL_MODE=read # read-only
  70. TOOL_MODE=all # everything (default)
  71. ```
  72. ## Claude Desktop Integration
  73. MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  74. Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  75. **Using npx:**
  76. ```json
  77. {
  78. "mcpServers": {
  79. "metabase": {
  80. "command": "npx",
  81. "args": ["@easecloudio/mcp-metabase-server"],
  82. "env": {
  83. "METABASE_URL": "https://your-metabase-instance.com",
  84. "METABASE_API_KEY": "your_metabase_api_key"
  85. }
  86. }
  87. }
  88. }
  89. ```
  90. **With tool filtering:**
  91. ```json
  92. {
  93. "mcpServers": {
  94. "metabase": {
  95. "command": "npx",
  96. "args": ["@easecloudio/mcp-metabase-server"],
  97. "env": {
  98. "METABASE_URL": "https://your-metabase-instance.com",
  99. "METABASE_API_KEY": "your_metabase_api_key",
  100. "TOOL_MODE": "essential"
  101. }
  102. }
  103. }
  104. }
  105. ```
  106. **Using a local build:**
  107. ```json
  108. {
  109. "mcpServers": {
  110. "metabase": {
  111. "command": "node",
  112. "args": ["/path/to/metabase-server/dist/index.js"],
  113. "env": {
  114. "METABASE_URL": "https://your-metabase-instance.com",
  115. "METABASE_API_KEY": "your_metabase_api_key"
  116. }
  117. }
  118. }
  119. }
  120. ```
  121. **Username / password fallback:**
  122. ```json
  123. {
  124. "mcpServers": {
  125. "metabase": {
  126. "command": "npx",
  127. "args": ["@easecloudio/mcp-metabase-server"],
  128. "env": {
  129. "METABASE_URL": "https://your-metabase-instance.com",
  130. "METABASE_USERNAME": "your_username",
  131. "METABASE_PASSWORD": "your_password"
  132. }
  133. }
  134. }
  135. }
  136. ```
  137. ## Available Tools
  138. <details>
  139. <summary><strong>Dashboard Management (27 tools)</strong></summary>
  140. ### Core CRUD
  141. | Tool | Description |
  142. |---|---|
  143. | `list_dashboards` | List all dashboards |
  144. | `get_dashboard` | Get a specific dashboard by ID |
  145. | `create_dashboard` | Create a new dashboard |
  146. | `update_dashboard` | Update an existing dashboard |
  147. | `delete_dashboard` | Delete / archive a dashboard |
  148. | `copy_dashboard` | Duplicate a dashboard (shallow or deep copy) |
  149. | `save_dashboard` | Save a complete dashboard object with nested data |
  150. | `save_dashboard_to_collection` | Move a dashboard into a specific collection |
  151. | `search_dashboards` | Search dashboards by name or description |
  152. | `favorite_dashboard` | Mark a dashboard as a favourite |
  153. | `unfavorite_dashboard` | Remove a dashboard from favourites |
  154. ### Card Layout
  155. | Tool | Description |
  156. |---|---|
  157. | `get_dashboard_cards` | Get all cards in a dashboard |
  158. | `add_card_to_dashboard` | Add a card with positioning |
  159. | `add_text_block` | Add a text or heading block to a dashboard |
  160. | `remove_card_from_dashboard` | Remove a card |
  161. | `update_dashboard_card` | Update card position, size, and settings |
  162. | `update_dashboard_cards` | Bulk-replace all cards on a dashboard |
  163. | `update_dashcard` | Update a specific dashcard's properties |
  164. | `execute_dashboard_card` | Execute a specific dashcard and return results |
  165. ### Public Sharing & Embedding
  166. | Tool | Description |
  167. |---|---|
  168. | `create_dashboard_public_link` | Create a public sharing link |
  169. | `delete_dashboard_public_link` | Remove the public link |
  170. | `list_public_dashboards` | List dashboards with public links |
  171. | `list_embeddable_dashboards` | List dashboards enabled for embedding |
  172. ### Revision, Audit & Discovery
  173. | Tool | Description |
  174. |---|---|
  175. | `get_dashboard_revisions` | Get revision history (audit trail) |
  176. | `revert_dashboard` | Revert to a previous revision |
  177. | `get_dashboard_related` | Get related content suggestions |
  178. | `get_dashboard_queries` | Extract all card queries with resolved field IDs |
  179. </details>
  180. <details>
  181. <summary><strong>Card / Question Management (21 tools)</strong></summary>
  182. ### Core CRUD
  183. | Tool | Description |
  184. |---|---|
  185. | `list_cards` | List all questions / cards |
  186. | `get_card` | Get a card by ID (includes full SQL / MBQL query) |
  187. | `create_card` | Create a new question |
  188. | `update_card` | Update an existing question |
  189. | `delete_card` | Delete / archive a question |
  190. | `copy_card` | Duplicate a card |
  191. | `move_cards` | Move one or more cards to a different collection |
  192. | `move_cards_to_collection` | Bulk-move cards from a source collection |
  193. ### Execution & Export
  194. | Tool | Description |
  195. |---|---|
  196. | `execute_card` | Run a card and return results |
  197. | `execute_pivot_card_query` | Run a card formatted as a pivot table |
  198. | `export_card_result` | Export results as CSV or JSON |
  199. ### Parameters
  200. | Tool | Description |
  201. |---|---|
  202. | `get_card_param_values` | Get available values for a card parameter |
  203. | `search_card_param_values` | Search / filter parameter values |
  204. | `get_card_param_remapping` | Get how parameter values are remapped for display |
  205. ### Metadata & Discovery
  206. | Tool | Description |
  207. |---|---|
  208. | `get_card_query_metadata` | Get column types and display names |
  209. | `get_card_dashboards` | List dashboards containing this card |
  210. | `get_card_series` | Get series data or related card suggestions |
  211. ### Public Sharing & Embedding
  212. | Tool | Description |
  213. |---|---|
  214. | `create_card_public_link` | Create a public sharing link |
  215. | `delete_card_public_link` | Remove the public link |
  216. | `list_public_cards` | List cards with public links |
  217. | `list_embeddable_cards` | List cards enabled for embedding |
  218. </details>
  219. <details>
  220. <summary><strong>Database Management (16 tools)</strong></summary>
  221. ### Core CRUD
  222. | Tool | Description |
  223. |---|---|
  224. | `list_databases` | List all database connections |
  225. | `get_database` | Get a specific database by ID |
  226. | `create_database_connection` | Create a new database connection |
  227. | `update_database` | Update a database connection's config or credentials |
  228. | `delete_database` | Permanently remove a database connection |
  229. | `add_sample_database` | Add the built-in H2 sample database with demo data |
  230. ### Querying
  231. | Tool | Description |
  232. |---|---|
  233. | `execute_query` | Execute a SQL query against a database |
  234. ### Schema & Sync
  235. | Tool | Description |
  236. |---|---|
  237. | `get_database_schema` | Get schema information |
  238. | `get_database_tables` | Get all tables in a database |
  239. | `get_database_metadata` | Get full metadata including all tables and field IDs |
  240. | `list_database_schemas` | List all schemas within a database |
  241. | `sync_database_schema` | Trigger a schema metadata sync |
  242. | `get_database_sync_status` | Check sync status |
  243. ### Diagnostics
  244. | Tool | Description |
  245. |---|---|
  246. | `check_database_health` | Check connection health |
  247. | `validate_database` | Validate connection settings before saving |
  248. | `test_database_connection` | Test an existing connection |
  249. </details>
  250. <details>
  251. <summary><strong>Table Management (17 tools)</strong></summary>
  252. ### Metadata
  253. | Tool | Description |
  254. |---|---|
  255. | `list_tables` | List tables (optionally filtered by database) |
  256. | `get_table` | Get table metadata by ID |
  257. | `get_table_metadata` | Get full query metadata including field IDs and types |
  258. | `get_table_fks` | Get foreign key relationships |
  259. | `get_table_related` | Find related tables via FK relationships |
  260. | `get_table_data` | Get a sample data preview from a table |
  261. | `get_field_id` | Look up a field ID by table ID + column name (returns MBQL ref) |
  262. ### Card Virtual Tables
  263. | Tool | Description |
  264. |---|---|
  265. | `get_card_table_fks` | Get FK relationships for a card's virtual table |
  266. | `get_card_table_query_metadata` | Get query metadata for a card's virtual table |
  267. ### Management
  268. | Tool | Description |
  269. |---|---|
  270. | `update_table` | Update display name, description, or visibility |
  271. | `update_tables` | Bulk-update multiple tables with the same config |
  272. | `reorder_table_fields` | Change the display order of fields |
  273. | `sync_table_schema` | Trigger a schema sync for a specific table |
  274. | `rescan_table_field_values` | Rescan field values (updates filter dropdowns) |
  275. | `discard_table_field_values` | Discard cached field values |
  276. ### CSV Upload (Metabase-managed tables)
  277. | Tool | Description |
  278. |---|---|
  279. | `append_csv_to_table` | Append new rows from CSV content |
  280. | `replace_table_csv` | Replace all table data with new CSV content |
  281. </details>
  282. <details>
  283. <summary><strong>Collections, Users & Search (13 tools)</strong></summary>
  284. ### Collections
  285. | Tool | Description |
  286. |---|---|
  287. | `list_collections` | List all collections |
  288. | `create_collection` | Create a new collection |
  289. | `get_collection` | Get collection details |
  290. | `update_collection` | Update name, description, color, or parent |
  291. | `delete_collection` | Delete a collection and its contents |
  292. | `get_collection_items` | List cards, dashboards, and sub-collections |
  293. | `move_to_collection` | Move a card or dashboard to a different collection |
  294. ### Users
  295. | Tool | Description |
  296. |---|---|
  297. | `list_users` | List all users |
  298. | `create_user` | Create a new user |
  299. ### Permissions
  300. | Tool | Description |
  301. |---|---|
  302. | `list_permission_groups` | List all permission groups |
  303. | `create_permission_group` | Create a new permission group |
  304. ### Search
  305. | Tool | Description |
  306. |---|---|
  307. | `search_content` | Search across all Metabase content |
  308. </details>
  309. <details>
  310. <summary><strong>Schema Cache — SQL to MBQL (2 tools)</strong></summary>
  311. These tools enable an AI to convert native SQL questions into interactive MBQL questions. Metabase has no REST API for this conversion — it requires field IDs, which these tools cache locally.
  312. **How it works:**
  313. 1. `get_card` — extract the SQL and `database_id`
  314. 2. `get_schema_cache` — get tables + field IDs for MBQL references like `["field", 42, null]`
  315. 3. AI translates SQL → MBQL using the cached field IDs
  316. 4. `create_card` — save the new interactive question
  317. Cache is stored at `~/.easecloud/metabase-mcp/cache/{url-hash}/` with a 24-hour TTL and scoped per Metabase instance.
  318. | Tool | Description |
  319. |---|---|
  320. | `get_schema_cache` | Return cached schema (auto-fetches if missing or stale) |
  321. | `refresh_schema_cache` | Force-refresh cache for one or all databases |
  322. </details>
  323. ## MCP Resources
  324. Access Metabase entities directly via `metabase://` URIs:
  325. | URI | Description |
  326. |---|---|
  327. | `metabase://dashboard/{id}` | Dashboard details |
  328. | `metabase://card/{id}` | Card / question details |
  329. | `metabase://database/{id}` | Database information |
  330. | `metabase://collection/{id}` | Collection details |
  331. | `metabase://user/{id}` | User information |
  332. | `metabase://table/{id}` | Table metadata |
  333. | `metabase://field/{id}` | Field information |
  334. ## Development
  335. ```bash
  336. npm install
  337. npm run build # compile TypeScript → dist/
  338. npm run watch # incremental rebuild
  339. npm run dev # build + start
  340. npm run inspector # launch MCP Inspector for debugging
  341. ```
  342. ## Debugging
  343. MCP servers communicate over stdio, which makes direct debugging awkward. Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
  344. ```bash
  345. npm run inspector
  346. ```
  347. The Inspector provides a browser UI for sending tool calls and inspecting responses.
  348. ## About EaseCloud
  349. EaseCloud is a cloud consulting and solutions company specializing in:
  350. - Cloud-native application development
  351. - AI & automation integrations
  352. - DevOps and infrastructure management
  353. - Data analytics and BI platform consulting
  354. We built this project to contribute to the open-source MCP ecosystem while demonstrating our expertise in integration, automation, and cloud solutions.
  355. If your team is adopting Metabase at scale or looking to integrate AI with your BI stack, [get in touch](https://easecloud.io) — we provide consulting, customization, and managed support for enterprises.
  356. 📧 [support@easecloud.io](mailto:support@easecloud.io)
  357. 🌐 [easecloud.io](https://easecloud.io)
  358. ## Bug Reports & Issues
  359. Found a bug or have a feature request?
  360. 🐛 [Create a GitHub issue](https://github.com/easecloudio/mcp-metabase-server/issues)
  361. Please include:
  362. - Metabase version
  363. - MCP server version
  364. - Steps to reproduce
  365. - Expected vs actual behavior
  366. - Any error messages or logs
  367. ## Contributing
  368. Contributions are welcome. Visit the [GitHub repository](https://github.com/easecloudio/mcp-metabase-server) to submit issues or pull requests.
  369. ## License
  370. MIT — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.