{"id":48746031,"url":"https://github.com/1luvc0d3/metabase-mcp","last_synced_at":"2026-04-21T05:01:06.659Z","repository":{"id":350762691,"uuid":"1208158068","full_name":"1luvc0d3/metabase-mcp","owner":"1luvc0d3","description":"MCP server connecting Claude to Metabase for natural language data analysis, dashboard management, and SQL queries","archived":false,"fork":false,"pushed_at":"2026-04-19T05:14:52.000Z","size":356,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T06:27:29.752Z","etag":null,"topics":["anthropic","claude","data-analysis","mcp","metabase","model-context-protocol","natural-language","sql"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@ai-1luvc0d3/metabase-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1luvc0d3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T22:36:09.000Z","updated_at":"2026-04-19T05:13:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/1luvc0d3/metabase-mcp","commit_stats":null,"previous_names":["1luvc0d3/metabase-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/1luvc0d3/metabase-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1luvc0d3%2Fmetabase-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1luvc0d3%2Fmetabase-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1luvc0d3%2Fmetabase-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1luvc0d3%2Fmetabase-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1luvc0d3","download_url":"https://codeload.github.com/1luvc0d3/metabase-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1luvc0d3%2Fmetabase-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32077837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","data-analysis","mcp","metabase","model-context-protocol","natural-language","sql"],"created_at":"2026-04-12T11:04:41.148Z","updated_at":"2026-04-21T05:01:06.653Z","avatar_url":"https://github.com/1luvc0d3.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metabase-mcp\n\n[![npm version](https://img.shields.io/npm/v/@ai-1luvc0d3/metabase-mcp.svg)](https://www.npmjs.com/package/@ai-1luvc0d3/metabase-mcp)\n[![npm downloads](https://img.shields.io/npm/dw/@ai-1luvc0d3/metabase-mcp.svg)](https://www.npmjs.com/package/@ai-1luvc0d3/metabase-mcp)\n[![CI](https://github.com/1luvc0d3/metabase-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/1luvc0d3/metabase-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node](https://img.shields.io/node/v/@ai-1luvc0d3/metabase-mcp.svg)](https://nodejs.org)\n[![Glama score](https://glama.ai/mcp/servers/1luvc0d3/metabase-mcp/badges/score.svg)](https://glama.ai/mcp/servers/1luvc0d3/metabase-mcp)\n\nThe **write-enabled, AI-augmented** [MCP](https://modelcontextprotocol.io/) server for [Metabase](https://www.metabase.com/) — create dashboards, ask questions in plain English, and get automated insights through Claude, on any Metabase version.\n\n## Why This One?\n\nMetabase shipped an [official MCP server in v0.60](https://www.metabase.com/docs/latest/ai/mcp) focused on read and search. This server complements it with **write operations, AI-generated insights, production security controls, and support for Metabase versions older than v0.60**.\n\n| Capability | @ai-1luvc0d3/metabase-mcp | Metabase Official (v0.60+) | Other community servers |\n|---|:--:|:--:|:--:|\n| Read dashboards / cards / databases | ✅ | ✅ | ✅ |\n| Write ops (create/update/delete cards, dashboards, collections) | ✅ | ❌ | partial |\n| Batch execution (parallel multi-op in one call) | ✅ | ❌ | ❌ |\n| Workflow pipelines (chained steps with output references) | ✅ | ❌ | ❌ |\n| Natural language → SQL (+ explain / optimize / validate) | ✅ | partial | ❌ |\n| Automated insights \u0026 trend analysis | ✅ | ❌ | ❌ |\n| SQL injection guardrails | ✅ | n/a | ❌ |\n| Tiered rate limiting (read / write / LLM) | ✅ | n/a | ❌ |\n| Audit logging with risk levels | ✅ | n/a | ❌ |\n| Token-optimized compact responses (default) | ✅ | ❌ | partial |\n| Server modes (read / write / full) | ✅ | ❌ | ❌ |\n| Works on Metabase \u0026lt; v0.60 (no upgrade required) | ✅ | ❌ | varies |\n| OAuth per-user permission scoping | ❌ (API key) | ✅ | varies |\n\n**Use this if:** you want Claude to *create* content in Metabase, you want AI-generated insights on query results, or you're on a Metabase version older than v0.60.\n\n**Use Metabase's official MCP if:** you're on v0.60+, only need read/search, and want per-user permission scoping via OAuth.\n\n## Features\n\n- **30 tools** across read, batch, workflow, write, NLQ, and insight categories\n- **Batch execution** -- run up to 20 read operations in parallel in a single call\n- **Workflow pipelines** -- chain tools sequentially with `$stepName.path` output references between steps\n- **Compact responses by default** -- all tools return compact JSON (~50% token reduction); opt into pretty-printing with `format: \"default\"`\n- **Natural language to SQL** -- ask questions, get SQL + results (powered by Claude)\n- **SQL guardrails** -- injection detection, DDL/DML blocking, dangerous pattern enforcement\n- **Tiered rate limiting** -- configurable per-minute limits for read, write, and LLM operations\n- **Audit logging** -- every operation logged with risk assessment\n- **Three server modes** -- `read` (safe default), `write`, or `full` (with AI insights)\n- **Schema caching** -- fast NLQ context for large databases\n\n## Quick Start\n\n### One-click install (recommended)\n\n1. Download the latest `metabase-mcp-*.mcpb` from [GitHub Releases](https://github.com/1luvc0d3/metabase-mcp/releases/latest)\n2. Double-click to install in Claude Desktop\n3. Enter your Metabase URL and API key when prompted — stored securely in the OS keychain\n\n### Using npx\n\n```bash\nnpx @ai-1luvc0d3/metabase-mcp\n```\n\n### Manual install\n\n```bash\nnpm install -g @ai-1luvc0d3/metabase-mcp\nmetabase-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/1luvc0d3/metabase-mcp.git\ncd metabase-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n## Configuration\n\nSet environment variables or create a `.env` file (see `.env.example`):\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `METABASE_URL` | Yes | - | Your Metabase instance URL |\n| `METABASE_API_KEY` | Yes | - | Metabase API key |\n| `MCP_MODE` | No | `read` | Server mode: `read`, `write`, or `full` |\n| `ANTHROPIC_API_KEY` | No | - | Enables NLQ and insight tools |\n| `METABASE_TIMEOUT` | No | `30000` | Request timeout (ms) |\n| `METABASE_MAX_ROWS` | No | `10000` | Max rows returned per query |\n| `LOG_LEVEL` | No | `info` | Logging: `debug`, `info`, `warn`, `error` |\n| `RATE_LIMIT_REQUESTS_PER_MINUTE` | No | `60` | Rate limit threshold |\n\n### Generate a Metabase API Key\n\n1. Go to your Metabase instance\n2. Navigate to **Admin** \u003e **Settings** \u003e **API Keys**\n3. Click **Create API Key**\n4. Copy the key and set it as `METABASE_API_KEY`\n\n## Claude Desktop Integration\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"metabase\": {\n      \"command\": \"npx\",\n      \"args\": [\"@ai-1luvc0d3/metabase-mcp\"],\n      \"env\": {\n        \"METABASE_URL\": \"https://your-metabase.example.com\",\n        \"METABASE_API_KEY\": \"mb_your_api_key_here\",\n        \"MCP_MODE\": \"read\"\n      }\n    }\n  }\n}\n```\n\n## Server Modes\n\n| Mode | Tools | Description |\n|------|-------|-------------|\n| `read` | 12 + NLQ | Read-only access, batch execution, and workflow pipelines |\n| `write` | 22 + NLQ | Adds create/update/delete for cards, dashboards, collections |\n| `full` | 30 | All tools including automated insights and trend analysis |\n\n### Available Tools\n\n**Read (always available)**\n`list_dashboards`, `get_dashboard`, `list_cards`, `get_card`, `execute_card`, `list_databases`, `get_database_schema`, `execute_query`, `search_content`, `get_collections`\n\n**Batch \u0026 Workflow (always available)**\n`batch_execute`, `run_workflow`\n\n**Write (write/full modes)**\n`create_card`, `update_card`, `delete_card`, `create_dashboard`, `update_dashboard`, `delete_dashboard`, `add_card_to_dashboard`, `remove_card_from_dashboard`, `create_collection`, `move_to_collection`\n\n**NLQ (requires ANTHROPIC_API_KEY)**\n`nlq_to_sql`, `explain_sql`, `optimize_sql`, `validate_sql`\n\n**Insights (full mode + ANTHROPIC_API_KEY)**\n`ask_data`, `generate_insights`, `compare_metrics`, `trend_analysis`\n\n## Examples\n\n### 1. Exploring your data\n\n\u003e **You**: What dashboards do we have related to customer retention?\n\nClaude uses `search_content` to find retention-related dashboards, then `get_dashboard` to summarize the key metrics. You see a ranked list with the most relevant results.\n\n\u003e **You**: Run the \"Monthly Active Users\" card for the last 90 days\n\nClaude calls `list_cards` to locate the card, then `execute_card` with the appropriate time filter. Results come back as a table you can ask follow-up questions about (\"what was the biggest dip and when?\").\n\n### 2. Ad-hoc SQL with safety rails\n\n\u003e **You**: Show me the top 10 products by revenue last quarter from the sales database\n\nClaude calls `list_databases` to find the sales database, `get_database_schema` to inspect the relevant tables, then generates and runs a `SELECT` query via `execute_query`. The query is validated against the SQL guardrails (no `DROP`/`DELETE`/`UNION`, single statement only) before execution. Audit log entry is written with the query and row count.\n\n\u003e **You**: DROP TABLE users\n\nRequest is blocked. Claude surfaces: *\"Blocked SQL pattern detected: DROP — this operation is not allowed.\"* The block is logged as a high-risk audit event.\n\n### 3. Natural language to SQL (requires ANTHROPIC_API_KEY)\n\n\u003e **You**: Which support agents closed the most tickets this week, and how does that compare to last week?\n\nClaude uses `nlq_to_sql` with the database schema as context to generate a comparative SQL query. You can ask it to `explain_sql` in plain English before running, or `optimize_sql` to suggest performance improvements — all before hitting your database.\n\n### 4. Saving a reusable query as a card (write mode)\n\n\u003e **You**: Save the MAU trend query we just ran as a card called \"MAU — Last 90 Days\" in the Growth collection\n\nClaude calls `get_collections` to find \"Growth\", then `create_card` with your validated SQL. The card now lives in your Metabase library and can be re-executed by name in future conversations via `execute_card` — no LLM tokens spent on re-generating the query.\n\n### 5. Batch execution — parallel data gathering\n\n\u003e **You**: Get me the details for dashboards 1, 3, and 7, plus the schema for the sales database\n\nClaude uses `batch_execute` to run all four operations in parallel in a single call:\n\n```json\n{\n  \"operations\": [\n    { \"tool\": \"get_dashboard\", \"args\": { \"dashboard_id\": 1 } },\n    { \"tool\": \"get_dashboard\", \"args\": { \"dashboard_id\": 3 } },\n    { \"tool\": \"get_dashboard\", \"args\": { \"dashboard_id\": 7 } },\n    { \"tool\": \"get_database_schema\", \"args\": { \"database_id\": 2 } }\n  ]\n}\n```\n\nOne tool call instead of four. Results come back with per-operation success/failure, so partial failures don't block the rest.\n\n### 6. Workflow pipelines — chained multi-step operations\n\n\u003e **You**: Find dashboards about revenue, get the first one's cards, and run the top card\n\nClaude uses `run_workflow` to chain the steps with output references:\n\n```json\n{\n  \"steps\": [\n    { \"name\": \"find\", \"tool\": \"search_content\", \"args\": { \"query\": \"revenue\", \"type\": \"dashboard\" } },\n    { \"name\": \"dash\", \"tool\": \"get_dashboard\", \"args\": { \"dashboard_id\": \"$find.results[0].id\" } },\n    { \"name\": \"data\", \"tool\": \"execute_card\", \"args\": { \"card_id\": \"$dash.dashcards[0].card_id\" } }\n  ]\n}\n```\n\nEach step can reference results from previous steps using `$stepName.path[index].field` syntax. One round trip instead of three back-and-forth exchanges.\n\n### 7. Automated insights on query results (full mode)\n\n\u003e **You**: Run last quarter's revenue query and tell me what's interesting\n\nClaude uses `execute_query` to run the query, then `generate_insights` which asks the Claude API to identify trends, outliers, and recommendations. You get a structured summary: headline number, 3-5 bullet points, and suggested follow-up questions.\n\n\u003e **Note on data privacy**: `generate_insights`, `ask_data`, `compare_metrics`, and `trend_analysis` send query result rows to the Anthropic API for analysis. See [Data Privacy Note](#data-privacy-note) for details.\n\n## Security\n\nThis server is designed for production use with multiple layers of protection:\n\n- **SQL Guardrails**: Only `SELECT` and `WITH` queries are allowed by default. DDL/DML statements (`DROP`, `DELETE`, `INSERT`, etc.) are blocked. Injection patterns (UNION, comments, multi-statement, file ops, time-based attacks) are detected and rejected.\n- **Tiered Rate Limiting**: Separate limits for read (120/min), write (30/min), and LLM (20/min) operations.\n- **Audit Logging**: Every operation is logged with risk assessment (low/medium/high). Sensitive fields are automatically redacted. Log files are created with secure permissions (owner-only read/write).\n- **Secret Isolation**: API keys are never exposed to tool handlers. Error responses from Metabase are sanitized to prevent credential leakage.\n- **Redirect Protection**: API key headers are never forwarded on HTTP redirects.\n\n### Data Privacy Note\n\nWhen using NLQ or insight tools (`ask_data`, `generate_insights`, etc.), **query result data is sent to the Anthropic API** for analysis. If your queries return sensitive data (PII, financial records, etc.), that data will be processed by Claude. Consider this when enabling NLQ features on databases containing sensitive information.\n\n## Privacy Policy\n\n**What this extension collects:**\n- Your Metabase API key and URL (stored locally in the OS keychain — never transmitted to us)\n- Your Anthropic API key, if provided (stored locally in the OS keychain — never transmitted to us)\n- No telemetry, analytics, or usage data is collected by this extension\n\n**What this extension transmits:**\n- All Metabase API calls (queries, dashboards, cards) go directly from your machine to your own Metabase instance\n- NLQ/insight tool usage sends your natural-language question, database schema context, and query result samples to the Anthropic API for processing (governed by [Anthropic's privacy policy](https://www.anthropic.com/legal/privacy))\n- If you don't provide an Anthropic API key, no data is sent to Anthropic — NLQ and insight tools are simply disabled\n\n**Data retention:**\n- This extension does not retain any data. Audit logs (if enabled via `AUDIT_LOG_FILE`) are written to your local filesystem only, with owner-only permissions (0600)\n\n**Third-party privacy policies:**\n- [Metabase Privacy Policy](https://www.metabase.com/privacy)\n- [Anthropic Privacy Policy](https://www.anthropic.com/legal/privacy)\n\n**Reporting security issues:** See [SECURITY.md](SECURITY.md) for responsible disclosure.\n\n## Troubleshooting\n\n### \"Cannot connect to Metabase\" / 401 errors\n- Verify `METABASE_URL` is correct and reachable (test: `curl $METABASE_URL/api/health`)\n- Verify `METABASE_API_KEY` is valid (regenerate in Metabase Admin \u003e Settings \u003e API Keys if needed)\n- The API key must have permissions for the databases you want to query\n\n### \"Blocked SQL pattern detected\" errors\n- Only `SELECT` and `WITH` queries are allowed by default\n- Even inside a `SELECT`, patterns like `UNION SELECT`, SQL comments (`--`, `/* */`), `xp_cmdshell`, `INTO OUTFILE`, etc. are blocked\n- To execute DML (`INSERT`, `UPDATE`, `DELETE`), you must run in `write` or `full` mode AND the SQL must still pass guardrails (it won't — by design)\n\n### \"Rate limit exceeded\" errors\n- Default limits: 120 reads/min, 30 writes/min, 20 LLM calls/min\n- Adjust with `RATE_LIMIT_REQUESTS_PER_MINUTE` env var\n- Wait for the retry-after period shown in the error\n\n### NLQ tools unavailable\n- Requires `ANTHROPIC_API_KEY` — verify it's set\n- Check it starts with `sk-` and has remaining credits\n- Insight tools additionally require `MCP_MODE=full`\n\n### Claude Desktop: extension installed but tools not appearing\n- Fully quit and restart Claude Desktop\n- Check logs: `~/Library/Logs/Claude/mcp*.log` on macOS\n- Verify `node --version` is \u003e= 18\n\n## Feedback Wanted\n\nThis project is young and your input shapes where it goes next — especially now that Metabase has shipped its own official MCP. A minute of your time helps a lot:\n\n- **Is this useful for your workflow?** Start a [GitHub Discussion](https://github.com/1luvc0d3/metabase-mcp/discussions) or [star the repo](https://github.com/1luvc0d3/metabase-mcp) — tells me where to invest.\n- **Which tools do you actually use?** Let me know in [Discussions](https://github.com/1luvc0d3/metabase-mcp/discussions) — helps prioritize what stays, what grows.\n- **Hit a bug?** [File an issue](https://github.com/1luvc0d3/metabase-mcp/issues/new) with your Metabase version, `MCP_MODE`, and reproduction steps.\n- **Missing a feature?** [Request it](https://github.com/1luvc0d3/metabase-mcp/issues/new) — especially something the [official Metabase MCP](https://www.metabase.com/docs/latest/ai/mcp) doesn't cover.\n- **Running in production?** I'd genuinely love to hear about it — open a Discussion or drop a note on the repo.\n\n## Support\n\n- **Bug reports / feature requests:** [GitHub Issues](https://github.com/1luvc0d3/metabase-mcp/issues)\n- **Questions / general feedback:** [GitHub Discussions](https://github.com/1luvc0d3/metabase-mcp/discussions)\n- **Security vulnerabilities:** [Private disclosure](https://github.com/1luvc0d3/metabase-mcp/security/advisories/new) — see [SECURITY.md](SECURITY.md)\n- **Response time:** typically within 5 business days\n\n## Development\n\n```bash\nnpm install         # Install dependencies\nnpm run build       # Compile TypeScript\nnpm run dev         # Watch mode\nnpm test            # Run all tests\nnpm run type-check  # Type checking\nnpm run lint        # Linting\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1luvc0d3%2Fmetabase-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1luvc0d3%2Fmetabase-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1luvc0d3%2Fmetabase-mcp/lists"}