# Metabase MCP Server - Connect AI Assistants to Your Metabase Analytics 🚀
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/jlowin/fastmcp)
A high-performance **Model Context Protocol (MCP) server** for **Metabase**, enabling AI assistants like **Claude**, **Cursor**, and other MCP clients to interact seamlessly with your Metabase instance. Query databases, execute SQL, manage dashboards, and automate analytics workflows with natural language through AI-powered database operations.
**Perfect for:** Data analysts, developers, and teams looking to integrate AI assistants with their Metabase business intelligence platform for automated SQL queries, dashboard management, and data exploration.
## ✨ Key Features
### 🗄️ Database Operations
- **List Databases**: Browse all configured Metabase databases
- **Table Discovery**: Explore tables with metadata and descriptions
- **Field Inspection**: Get detailed field/column information with smart pagination
### 📊 Query & Analytics
- **SQL Execution**: Run native SQL queries with parameter support and templating
- **Card Management**: Execute, create, and manage Metabase questions/cards
- **Collection Organization**: Create and manage collections for better organization
- **Natural Language Queries**: Let AI assistants translate questions into SQL
### 🔐 Authentication & Security
- **API Key Support**: Secure authentication via Metabase API keys (recommended)
- **Session-based Auth**: Alternative email/password authentication
- **Environment Variables**: Secure credential management via `.env` files
### 🤖 AI Assistant Integration
- **Claude Desktop**: Native integration with Anthropic's Claude AI
- **Cursor IDE**: Seamless integration for AI-assisted development
- **Any MCP Client**: Compatible with all Model Context Protocol clients
## 🚀 Quick Start
### Prerequisites
- Python 3.12+
- Metabase instance with API access
- uv package manager (recommended) or pip
### Installation
#### Using uv (Recommended)
```bash
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/yourusername/metabase-mcp.git
cd metabase-mcp
# Install dependencies
uv sync
```
#### Using pip
```bash
# Clone and install
git clone https://github.com/yourusername/metabase-mcp.git
cd metabase-mcp
pip install -r requirements.txt
```
## ⚙️ Configuration
Create a `.env` file with your Metabase credentials:
```bash
cp .env.example .env
```
### Configuration Options
#### Option 1: API Key Authentication (Recommended)
```env
METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-here
```
#### Option 2: Email/Password Authentication
```env
METABASE_URL=https://your-metabase-instance.com
METABASE_USER_EMAIL=your-email@example.com
METABASE_PASSWORD=your-password
```
#### Optional: Custom Host/Port for SSE/HTTP
```env
HOST=localhost # Default: 0.0.0.0
PORT=9000 # Default: 8000
```
## Usage
### Run the Server
```bash
# STDIO transport (default)
uv run python server.py
# SSE transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --sse
# HTTP transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --http
# Custom host and port via environment variables
HOST=localhost PORT=9000 uv run python server.py --sse
HOST=192.168.1.100 PORT=8080 uv run python server.py --http
# Set environment variables persistently
export HOST=localhost
export PORT=9000
uv run python server.py --sse
```
### FastMCP CLI Integration
```bash
# Run with FastMCP CLI
fastmcp run server.py
# Install as Claude Desktop MCP server
fastmcp install server.py -n "Metabase MCP"
```
### Cursor Integration
You can manually configure Cursor by editing your Cursor settings. Example configurations are available in the `config/` directory.
**For SSE transport**: You must start the server before using Cursor:
```bash
uv run python server.py --sse 8000
```
### Claude Integration
After running `uv sync`, you can find the Python executable at `/path/to/repo/.venv/bin/python`.
To integrate with Claude, add or update the configuration file at `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"metabase-mcp-server": {
"command": "/path/to/repo/.venv/bin/python",
"args": ["/path/to/repo/server.py"]
}
}
}
```
## 🛠️ Available Tools
### Database Operations
| Tool | Description |
|------|------------|
| `list_databases` | List all configured databases in Metabase |
| `list_tables` | Get all tables in a specific database with metadata |
| `get_table_fields` | Retrieve field/column information for a table |
### Query Operations
| Tool | Description |
|------|------------|
| `execute_query` | Execute native SQL queries with parameter support |
| `execute_card` | Run saved Metabase questions/cards |
### Card Management
| Tool | Description |
|------|------------|
| `list_cards` | List all saved questions/cards |
| `create_card` | Create new questions/cards with SQL queries |
### Collection Management
| Tool | Description |
|------|------------|
| `list_collections` | Browse all collections |
| `create_collection` | Create new collections for organization |
## Transport Methods
The server supports multiple transport methods:
- **STDIO** (default): For IDE integration (Cursor, Claude Desktop)
- **SSE**: Server-Sent Events for web applications
- **HTTP**: Standard HTTP for API access
```bash
uv run python server.py # STDIO (default)
uv run python server.py --sse # SSE (HOST=0.0.0.0, PORT=8000)
uv run python server.py --http # HTTP (HOST=0.0.0.0, PORT=8000)
HOST=localhost PORT=9000 uv run python server.py --sse # Custom host/port
```
## 🧪 Development
### Setup Development Environment
```bash
# Install with dev dependencies
uv sync --group dev
# Or with pip
pip install -r requirements-dev.txt
```
### Code Quality
```bash
# Run linting
uv run ruff check .
# Format code
uv run ruff format .
# Type checking
uv run mypy server.py
```
## 📚 Usage Examples
### Query Examples
```python
# List all databases
databases = await list_databases()
# Execute a SQL query
result = await execute_query(
database_id=1,
query="SELECT * FROM users LIMIT 10"
)
# Create and run a card
card = await create_card(
name="Active Users Report",
database_id=1,
query="SELECT COUNT(*) FROM users WHERE active = true",
collection_id=2
)
```
## 📁 Project Structure
```
metabase-mcp/
├── server.py # Main MCP server implementation
├── setup.py # Setup and installation script
├── pyproject.toml # Project configuration and dependencies
├── .env.example # Environment variables template
└── config/ # Configuration examples for IDE integration
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
MIT License - see LICENSE file for details
## 🔗 Resources
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Metabase API Documentation](https://www.metabase.com/docs/latest/api-documentation)
- [Claude Desktop Documentation](https://claude.ai/desktop)
- [Cursor IDE](https://cursor.sh/)
## 🏷️ Keywords & Topics
`metabase` `mcp` `model-context-protocol` `claude` `cursor` `ai-assistant` `fastmcp` `sql` `database` `analytics` `business-intelligence` `bi` `data-analysis` `anthropic` `llm` `python` `automation` `api` `data-science` `query-builder` `natural-language-sql`
## ⭐ Star History
If you find this project useful, please consider giving it a star! It helps others discover this tool.
## 🔍 Use Cases
- **Natural Language Database Queries**: Ask Claude to query your Metabase databases using plain English
- **Automated Report Generation**: Use AI to create and manage Metabase cards and collections
- **Data Exploration**: Let AI assistants help you discover insights from your data
- **SQL Query Assistance**: Get help writing and optimizing SQL queries through AI
- **Dashboard Management**: Automate the creation and organization of Metabase dashboards
- **Data Analysis Workflows**: Integrate AI-powered analytics into your development workflow
Raw data
{
"_id": null,
"home_page": null,
"name": "metabase-fastmcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, ai-assistant, analytics, anthropic, api, automation, bi, business-intelligence, chatgpt, claude, cursor, data-analysis, database, fastmcp, llm, mcp, metabase, model-context-protocol, python, sql",
"author": null,
"author_email": "cheukyin175 <cheukyin175@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f7/00/bdc966061f12b13f7baa400beb1ae5e1a1f459e38f9cf138c2bc681dfc71/metabase_fastmcp-0.1.0.tar.gz",
"platform": null,
"description": "# Metabase MCP Server - Connect AI Assistants to Your Metabase Analytics \ud83d\ude80\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/jlowin/fastmcp)\n\nA high-performance **Model Context Protocol (MCP) server** for **Metabase**, enabling AI assistants like **Claude**, **Cursor**, and other MCP clients to interact seamlessly with your Metabase instance. Query databases, execute SQL, manage dashboards, and automate analytics workflows with natural language through AI-powered database operations.\n\n**Perfect for:** Data analysts, developers, and teams looking to integrate AI assistants with their Metabase business intelligence platform for automated SQL queries, dashboard management, and data exploration.\n\n## \u2728 Key Features\n\n### \ud83d\uddc4\ufe0f Database Operations\n- **List Databases**: Browse all configured Metabase databases\n- **Table Discovery**: Explore tables with metadata and descriptions\n- **Field Inspection**: Get detailed field/column information with smart pagination\n\n### \ud83d\udcca Query & Analytics\n- **SQL Execution**: Run native SQL queries with parameter support and templating\n- **Card Management**: Execute, create, and manage Metabase questions/cards\n- **Collection Organization**: Create and manage collections for better organization\n- **Natural Language Queries**: Let AI assistants translate questions into SQL\n\n### \ud83d\udd10 Authentication & Security\n- **API Key Support**: Secure authentication via Metabase API keys (recommended)\n- **Session-based Auth**: Alternative email/password authentication\n- **Environment Variables**: Secure credential management via `.env` files\n\n### \ud83e\udd16 AI Assistant Integration\n- **Claude Desktop**: Native integration with Anthropic's Claude AI\n- **Cursor IDE**: Seamless integration for AI-assisted development\n- **Any MCP Client**: Compatible with all Model Context Protocol clients\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n- Python 3.12+\n- Metabase instance with API access\n- uv package manager (recommended) or pip\n\n### Installation\n\n#### Using uv (Recommended)\n```bash\n# Install uv if not already installed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone https://github.com/yourusername/metabase-mcp.git\ncd metabase-mcp\n\n# Install dependencies\nuv sync\n```\n\n#### Using pip\n```bash\n# Clone and install\ngit clone https://github.com/yourusername/metabase-mcp.git\ncd metabase-mcp\npip install -r requirements.txt\n```\n\n## \u2699\ufe0f Configuration\n\nCreate a `.env` file with your Metabase credentials:\n\n```bash\ncp .env.example .env\n```\n\n### Configuration Options\n\n#### Option 1: API Key Authentication (Recommended)\n```env\nMETABASE_URL=https://your-metabase-instance.com\nMETABASE_API_KEY=your-api-key-here\n```\n\n#### Option 2: Email/Password Authentication\n```env\nMETABASE_URL=https://your-metabase-instance.com\nMETABASE_USER_EMAIL=your-email@example.com\nMETABASE_PASSWORD=your-password\n```\n\n#### Optional: Custom Host/Port for SSE/HTTP\n```env\nHOST=localhost # Default: 0.0.0.0\nPORT=9000 # Default: 8000\n```\n\n## Usage\n\n### Run the Server\n\n```bash\n# STDIO transport (default)\nuv run python server.py\n\n# SSE transport (uses HOST=0.0.0.0, PORT=8000 by default)\nuv run python server.py --sse\n\n# HTTP transport (uses HOST=0.0.0.0, PORT=8000 by default)\nuv run python server.py --http\n\n# Custom host and port via environment variables\nHOST=localhost PORT=9000 uv run python server.py --sse\nHOST=192.168.1.100 PORT=8080 uv run python server.py --http\n\n# Set environment variables persistently\nexport HOST=localhost\nexport PORT=9000\nuv run python server.py --sse\n```\n\n### FastMCP CLI Integration\n\n```bash\n# Run with FastMCP CLI\nfastmcp run server.py\n\n# Install as Claude Desktop MCP server\nfastmcp install server.py -n \"Metabase MCP\"\n```\n\n### Cursor Integration\n\nYou can manually configure Cursor by editing your Cursor settings. Example configurations are available in the `config/` directory.\n\n**For SSE transport**: You must start the server before using Cursor:\n```bash\nuv run python server.py --sse 8000\n```\n\n### Claude Integration\nAfter running `uv sync`, you can find the Python executable at `/path/to/repo/.venv/bin/python`.\nTo integrate with Claude, add or update the configuration file at `~/Library/Application\\ Support/Claude/claude_desktop_config.json`:\n```json\n{\n \"mcpServers\": {\n \"metabase-mcp-server\": {\n \"command\": \"/path/to/repo/.venv/bin/python\",\n \"args\": [\"/path/to/repo/server.py\"]\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f Available Tools\n\n### Database Operations\n| Tool | Description |\n|------|------------|\n| `list_databases` | List all configured databases in Metabase |\n| `list_tables` | Get all tables in a specific database with metadata |\n| `get_table_fields` | Retrieve field/column information for a table |\n\n### Query Operations\n| Tool | Description |\n|------|------------|\n| `execute_query` | Execute native SQL queries with parameter support |\n| `execute_card` | Run saved Metabase questions/cards |\n\n### Card Management\n| Tool | Description |\n|------|------------|\n| `list_cards` | List all saved questions/cards |\n| `create_card` | Create new questions/cards with SQL queries |\n\n### Collection Management\n| Tool | Description |\n|------|------------|\n| `list_collections` | Browse all collections |\n| `create_collection` | Create new collections for organization |\n\n## Transport Methods\n\nThe server supports multiple transport methods:\n\n- **STDIO** (default): For IDE integration (Cursor, Claude Desktop)\n- **SSE**: Server-Sent Events for web applications\n- **HTTP**: Standard HTTP for API access\n\n```bash\nuv run python server.py # STDIO (default)\nuv run python server.py --sse # SSE (HOST=0.0.0.0, PORT=8000)\nuv run python server.py --http # HTTP (HOST=0.0.0.0, PORT=8000)\nHOST=localhost PORT=9000 uv run python server.py --sse # Custom host/port\n```\n\n## \ud83e\uddea Development\n\n### Setup Development Environment\n\n```bash\n# Install with dev dependencies\nuv sync --group dev\n\n# Or with pip\npip install -r requirements-dev.txt\n```\n\n### Code Quality\n\n```bash\n# Run linting\nuv run ruff check .\n\n# Format code\nuv run ruff format .\n\n# Type checking\nuv run mypy server.py\n```\n\n\n## \ud83d\udcda Usage Examples\n\n### Query Examples\n\n```python\n# List all databases\ndatabases = await list_databases()\n\n# Execute a SQL query\nresult = await execute_query(\n database_id=1,\n query=\"SELECT * FROM users LIMIT 10\"\n)\n\n# Create and run a card\ncard = await create_card(\n name=\"Active Users Report\",\n database_id=1,\n query=\"SELECT COUNT(*) FROM users WHERE active = true\",\n collection_id=2\n)\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nmetabase-mcp/\n\u251c\u2500\u2500 server.py # Main MCP server implementation\n\u251c\u2500\u2500 setup.py # Setup and installation script\n\u251c\u2500\u2500 pyproject.toml # Project configuration and dependencies\n\u251c\u2500\u2500 .env.example # Environment variables template\n\u2514\u2500\u2500 config/ # Configuration examples for IDE integration\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE file for details\n\n## \ud83d\udd17 Resources\n\n- [FastMCP Documentation](https://github.com/jlowin/fastmcp)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Metabase API Documentation](https://www.metabase.com/docs/latest/api-documentation)\n- [Claude Desktop Documentation](https://claude.ai/desktop)\n- [Cursor IDE](https://cursor.sh/)\n\n## \ud83c\udff7\ufe0f Keywords & Topics\n\n`metabase` `mcp` `model-context-protocol` `claude` `cursor` `ai-assistant` `fastmcp` `sql` `database` `analytics` `business-intelligence` `bi` `data-analysis` `anthropic` `llm` `python` `automation` `api` `data-science` `query-builder` `natural-language-sql`\n\n## \u2b50 Star History\n\nIf you find this project useful, please consider giving it a star! It helps others discover this tool.\n\n## \ud83d\udd0d Use Cases\n\n- **Natural Language Database Queries**: Ask Claude to query your Metabase databases using plain English\n- **Automated Report Generation**: Use AI to create and manage Metabase cards and collections\n- **Data Exploration**: Let AI assistants help you discover insights from your data\n- **SQL Query Assistance**: Get help writing and optimizing SQL queries through AI\n- **Dashboard Management**: Automate the creation and organization of Metabase dashboards\n- **Data Analysis Workflows**: Integrate AI-powered analytics into your development workflow \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol (MCP) server for Metabase - Connect AI assistants like Claude and Cursor to your Metabase analytics platform",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/hyeongjun-dev/metabase-mcp",
"Issues": "https://github.com/hyeongjun-dev/metabase-mcp/issues",
"Repository": "https://github.com/hyeongjun-dev/metabase-mcp"
},
"split_keywords": [
"ai",
" ai-assistant",
" analytics",
" anthropic",
" api",
" automation",
" bi",
" business-intelligence",
" chatgpt",
" claude",
" cursor",
" data-analysis",
" database",
" fastmcp",
" llm",
" mcp",
" metabase",
" model-context-protocol",
" python",
" sql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "21b2ffdd1a62f120a5eb307df24fcc37d5a038750470e865dce10b9cf82b0240",
"md5": "f93d0bda6d0c69d418a9132e23c93eb5",
"sha256": "76e99f5b38dca12ee81e48e6b0c0395bf0095c0a79aeb6c5daabd1f8f23a8330"
},
"downloads": -1,
"filename": "metabase_fastmcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f93d0bda6d0c69d418a9132e23c93eb5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 47630,
"upload_time": "2025-10-10T10:29:48",
"upload_time_iso_8601": "2025-10-10T10:29:48.448750Z",
"url": "https://files.pythonhosted.org/packages/21/b2/ffdd1a62f120a5eb307df24fcc37d5a038750470e865dce10b9cf82b0240/metabase_fastmcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f700bdc966061f12b13f7baa400beb1ae5e1a1f459e38f9cf138c2bc681dfc71",
"md5": "ce4f06b3a055f21dffb7056527a5deb0",
"sha256": "eeeafeebbc88fde22c251a45747f44e3fa403b0a510db511ba9990fd16124c06"
},
"downloads": -1,
"filename": "metabase_fastmcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ce4f06b3a055f21dffb7056527a5deb0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 36650,
"upload_time": "2025-10-10T10:29:49",
"upload_time_iso_8601": "2025-10-10T10:29:49.931596Z",
"url": "https://files.pythonhosted.org/packages/f7/00/bdc966061f12b13f7baa400beb1ae5e1a1f459e38f9cf138c2bc681dfc71/metabase_fastmcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 10:29:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hyeongjun-dev",
"github_project": "metabase-mcp",
"github_not_found": true,
"lcname": "metabase-fastmcp"
}
JSON
