{"_id":"@cyberbiz-corp/metabase-mcp","name":"@cyberbiz-corp/metabase-mcp","dist-tags":{"latest":"1.1.5"},"versions":{"1.1.5":{"name":"@cyberbiz-corp/metabase-mcp","version":"1.1.5","description":"A high-performance MCP server for Metabase analytics integration with response optimization and robust error handling","type":"module","author":{"name":"Jericho Sequitin","url":"https://github.com/jerichosequitin"},"bin":{"metabase-mcp":"build/src/index.js"},"scripts":{"build":"npm run validate && tsc && npm test && node -e \"require('fs').chmodSync('build/src/index.js', '755')\"","build:clean":"rm -rf build && npm run build","build:fast":"tsc && node -e \"require('fs').chmodSync('build/src/index.js', '755')\"","prepare":"npm run build:fast && husky","watch":"tsc --watch","inspector":"npx @modelcontextprotocol/inspector build/src/index.js","start":"node build/src/index.js","dev":"tsc && node build/src/index.js","dev:watch":"npm run build && concurrently \"tsc --watch\" \"nodemon --delay 2 build/src/index.js\"","lint":"eslint src/","lint:fix":"eslint src/ --fix","format":"prettier --write \"src/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\"","type-check":"tsc --noEmit","validate":"npm run type-check && npm run lint && npm run format:check","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:all":"./scripts/test-all.sh","clean":"rm -rf build node_modules/.cache","version":"node scripts/sync-version.cjs && git add manifest.json Dockerfile src/server.ts","mcpb:build":"npm run build && node scripts/build-mcpb.cjs","mcpb:validate":"echo 'MCPB validation - checking manifest structure' && node -e \"const fs = require('fs'); const manifest = JSON.parse(fs.readFileSync('manifest.json', 'utf8')); console.log('Manifest valid:', manifest.name, manifest.version);\""},"dependencies":{"@modelcontextprotocol/sdk":"^1.23.0","@types/xlsx":"^0.0.35","dotenv":"^16.3.1","xlsx":"https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz","zod":"^3.25.0"},"devDependencies":{"@types/node":"^20.17.22","@vitest/coverage-v8":"^4.0.15","concurrently":"^8.2.2","eslint":"^9.39.2","husky":"^9.0.11","nodemon":"^3.0.2","prettier":"^3.2.5","typescript":"^5.3.3","typescript-eslint":"^8.49.0","vitest":"^4.0.15"},"keywords":["metabase","mcp","model-context-protocol","ai","claude","analytics","business-intelligence","sql"],"repository":{"type":"git","url":"git+https://github.com/sinleadpro/metabase-mcp.git"},"homepage":"https://github.com/sinleadpro/metabase-mcp#readme","bugs":{"url":"https://github.com/sinleadpro/metabase-mcp/issues"},"license":"MIT","engines":{"node":">=18.0.0"},"_id":"@cyberbiz-corp/metabase-mcp@1.1.5","gitHead":"68ea7dfdaa44b172090abbfb1dcf50e8923098db","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-CW1YY20jSPIV40tIIcA40drWN4nGkdlk+UM92p8kDN5QS8snfr/YKMlr1KiznEalWG9hS6YVVCIMpGYLASLSBQ==","shasum":"a697fa7ffc0bf83b868e8e4fd808419bf290e59b","tarball":"https://registry.npmjs.org/@cyberbiz-corp/metabase-mcp/-/metabase-mcp-1.1.5.tgz","fileCount":135,"unpackedSize":795939,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFqd9UyM6eyCjszd01bAAY9ttB2h9RCQ7/kNpUdH58mkAiEAx2kWRIMX2ac8wERvwRa7WobvWPPb/kncu2HqqaYZjOQ="}]},"_npmUser":{"name":"cyberbiz-corp","email":"npm2@cyberbiz.io"},"directories":{},"maintainers":[{"name":"cyberbiz-corp","email":"npm2@cyberbiz.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/metabase-mcp_1.1.5_1776066742473_0.7370926890618235"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-13T07:52:22.363Z","1.1.5":"2026-04-13T07:52:22.655Z","modified":"2026-04-13T07:52:22.877Z"},"maintainers":[{"name":"cyberbiz-corp","email":"npm2@cyberbiz.io"}],"description":"A high-performance MCP server for Metabase analytics integration with response optimization and robust error handling","homepage":"https://github.com/sinleadpro/metabase-mcp#readme","keywords":["metabase","mcp","model-context-protocol","ai","claude","analytics","business-intelligence","sql"],"repository":{"type":"git","url":"git+https://github.com/sinleadpro/metabase-mcp.git"},"author":{"name":"Jericho Sequitin","url":"https://github.com/jerichosequitin"},"bugs":{"url":"https://github.com/sinleadpro/metabase-mcp/issues"},"license":"MIT","readme":"# Metabase MCP\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jerichosequitin/metabase-mcp)\n[![npm version](https://img.shields.io/npm/v/@jerichosequitin/metabase-mcp)](https://www.npmjs.com/package/@jerichosequitin/metabase-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![GitHub stars](https://img.shields.io/github/stars/jerichosequitin/metabase-mcp)](https://github.com/jerichosequitin/metabase-mcp/stargazers)\n\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/jerichosequitin)\n\nA high-performance Model Context Protocol server for AI integration with Metabase analytics platforms. Features response optimization, robust error handling, and comprehensive data access tools.\n\n\n \n\n\n## Key Features\n\n- **Response Optimization**: Up to 90% token reduction for efficient AI context usage\n- **Robust Error Handling**: Comprehensive error handling with structured, actionable responses\n- **Smart Caching**: Multi-layer caching with configurable TTL for improved performance\n- **Unified Commands**: `list`, `retrieve`, `search`, `execute`, and `export` tools\n- **Dual Authentication**: API key or email/password authentication\n- **Large Data Export**: Export up to 1M rows in CSV, JSON, and XLSX formats\n- **Read-Only Mode**: Enabled by default to restrict execute to SELECT queries only\n\n## Installation\n\n### Option 1: Claude Desktop\n\nInstall directly from the [Claude Desktop Directory](https://claude.ai/directory/ant.dir.gh.jerichosequitin.metabase), or:\n\n1. Download `metabase-mcp.mcpb` from [Releases](https://github.com/jerichosequitin/metabase-mcp/releases)\n2. Open the `.mcpb` file with Claude Desktop to install\n3. Configure your Metabase credentials in Claude Desktop's extension settings\n\n### Option 2: Manual Configuration\n\nAdd the following to your MCP client configuration:\n\n```jsonc\n{\n \"mcpServers\": {\n \"metabase-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@jerichosequitin/metabase-mcp\"],\n \"env\": {\n // Required\n \"METABASE_URL\": \"https://your-metabase-instance.com\",\n\n // Authentication (choose one)\n \"METABASE_API_KEY\": \"your_api_key_here\", // API key (recommended)\n \"METABASE_USER_EMAIL\": \"\", // OR email/password\n \"METABASE_PASSWORD\": \"\",\n\n // Optional (defaults shown)\n \"EXPORT_DIRECTORY\": \"~/Downloads/Metabase\", // Export location\n \"METABASE_READ_ONLY_MODE\": \"true\", // Restrict to SELECT queries\n \"LOG_LEVEL\": \"info\", // debug, info, warn, error, fatal (debug enables pretty JSON)\n \"CACHE_TTL_MS\": \"600000\", // 10 minutes\n \"REQUEST_TIMEOUT_MS\": \"600000\" // 10 minutes\n }\n }\n }\n}\n```\n\n### Option 3: Docker\n\nFor containerized deployments without installing Node.js. Add to your MCP client configuration:\n\n```jsonc\n{\n \"mcpServers\": {\n \"metabase-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\", \"--init\",\n \"-e\", \"METABASE_URL=https://your-metabase-instance.com\",\n \"-e\", \"METABASE_API_KEY=your_api_key\",\n // Optional: mount volume for exports\n // \"-v\", \"~/Downloads/Metabase:/home/node/exports\",\n \"ghcr.io/jerichosequitin/metabase-mcp:latest\"\n ]\n }\n }\n}\n```\n\nOr build locally: `docker build -t metabase-mcp .` and use `metabase-mcp` as the image name.\n\n**Required flags:** `-i` (interactive, for MCP stdio), `--rm` (cleanup), `--init` (signal handling)\n\n**Environment variables:** Pass via `-e` flags. See [Manual Configuration](#option-2-manual-configuration) for all options. Docker defaults: `LOG_LEVEL=info`, `METABASE_READ_ONLY_MODE=true`, `EXPORT_DIRECTORY=/home/node/exports`.\n\n## Available Tools\n\n### `list`\nFetch all records for a resource type with optimized responses returning only essential fields.\n- **Models**: `cards`, `dashboards`, `tables`, `databases`, `collections`\n- **Pagination**: `offset`/`limit` parameters for large datasets\n\n### `retrieve`\nGet detailed information for specific items by ID with concurrent processing.\n- **Models**: `card`, `dashboard`, `table`, `database`, `collection`, `field`\n- **Batch Support**: Up to 50 IDs per request\n- **Pagination**: `table_offset`/`table_limit` for databases with many tables\n\n### `search`\nSearch across all Metabase items using the native search API.\n- **Filtering**: By model type, database ID, or content\n- **Options**: Search native SQL queries, include dashboard questions\n\n### `execute`\nExecute SQL queries or run saved cards with configurable row limits (default: 100, max: 500).\n- **SQL Mode**: Custom queries with `database_id` and `query`\n- **Card Mode**: Saved cards with `card_id` and optional `card_parameters` for filtering\n- **Security**: Respects Read-Only Mode (blocks INSERT, UPDATE, DELETE, DROP, etc.)\n\n### `export`\nExport large datasets up to 1M rows to the configured export directory.\n- **Formats**: CSV, JSON, XLSX\n- **SQL Mode**: Export custom query results\n- **Card Mode**: Export saved card results with optional filtering\n- **Note**: When using hosted remote deployments (e.g., Glama), exported files are saved inside the container and are inaccessible. Use `execute` for query results directly, or run locally via npx/Docker for full export functionality.\n\n### `clear_cache`\nClear internal cache with granular control.\n- **Targets**: Individual model caches, list caches, or bulk operations (`all`, `all-lists`, `all-individual`)\n\n## For Developers\n\n### Prerequisites\n- Node.js 18.0.0 or higher\n- Active Metabase instance\n\n### Setup\n\n```bash\ngit clone https://github.com/jerichosequitin/metabase-mcp.git\ncd metabase-mcp\nnpm install\nnpm run build\n```\n\nThen configure your MCP client to use the local build:\n\n```jsonc\n{\n \"mcpServers\": {\n \"metabase-mcp\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/metabase-mcp/build/src/index.js\"],\n \"env\": { /* see Manual Configuration for options */ }\n }\n }\n}\n```\n\n### Debugging\n\nUse the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for development:\n\n```bash\nnpm run inspector\n```\n\n### Testing\n\n```bash\nnpm test # Run tests\nnpm run test:coverage # Coverage report\n```\n\n### Building MCPB Package\n\n```bash\nnpm run mcpb:build\n```\n\nCreates `metabase-mcp-{version}.mcpb` ready for GitHub Releases.\n\n## Security\n\n**Read-Only Mode** is enabled by default (`METABASE_READ_ONLY_MODE=true`), restricting the `execute` tool to SELECT queries only. Write operations (INSERT, UPDATE, DELETE, DROP, etc.) are blocked. Set to `false` to allow write operations.\n\n**Authentication**: API key authentication is recommended over email/password for production use.\n\n## License\n\nThis project is licensed under the MIT License.\n","readmeFilename":"README.md","_rev":"1-bf9cbc2e5df71e85b8321f696650608f"}