Content
# Metabase MCP Server - Connect AI Assistants to Your Metabase Analytics
[](https://badge.fury.io/py/metabase-mcp)
[](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
- **MongoDB Support**: Execute native MongoDB queries with automatic JSON conversion for aggregation pipelines
- **Card Management**: Execute, create, and manage Metabase questions/cards (SQL and MongoDB)
- **Collection Organization**: Create and manage collections for better organization
- **Natural Language Queries**: Let AI assistants translate questions into SQL or MongoDB queries
### 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
### Enhanced Performance & Reliability
- **Context-aware Logging**: Real-time logging with debug, info, warning, and error levels visible to AI clients
- **Proper Error Handling**: FastMCP `ToolError` exceptions for better error messages and debugging
- **Middleware Stack**: Built-in error handling and logging middleware for production reliability
- **Best Practices**: Follows latest FastMCP patterns with duplicate prevention and clean configuration
- **Modern Python**: Uses Python 3.12+ type hints (`|` syntax) for better type safety
## Quick Start
### Prerequisites
- Python 3.12+
- Metabase instance with API access
- `uvx` or `uv` package manager
### Installation
#### Option 1: Using uvx (Easiest - No Installation Required)
```bash
# Run directly without installing (like npx for Python)
uvx metabase-mcp
# With environment variables
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp
```
#### Option 2: Install from PyPI
```bash
# Install globally
uv tool install metabase-mcp
# Or with pip
pip install metabase-mcp
# Then run
metabase-mcp
```
#### Option 3: Development Setup (From Source)
```bash
# Clone the repository
git clone https://github.com/cheukyin175/metabase-mcp.git
cd metabase-mcp
# Install dependencies
uv sync
# Run the server
uv run python server.py
```
## 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: Metabase API HTTP Timeout
```env
METABASE_HTTP_TIMEOUT=30.0 # Default: 30.0 seconds
```
#### Optional: Custom Host/Port for SSE/HTTP
```env
HOST=localhost # Default: 0.0.0.0
PORT=9000 # Default: 8000
```
## Usage
### Run the Server
#### Quick Start (No Setup Required)
```bash
# Run directly with uvx
uvx metabase-mcp
# With custom Metabase instance
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp
```
#### From Source (Development)
```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
```
### Cursor Integration
You can manually configure Cursor by editing your Cursor settings.
**For SSE transport**: You must start the server before using Cursor:
```bash
uv run python server.py --sse
```
### Claude Desktop Integration
#### Option 1: Using uvx (Recommended)
Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"metabase-mcp": {
"command": "uvx",
"args": ["metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase-instance.com",
"METABASE_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Option 2: Using Local Installation
If you've cloned the repository:
```json
{
"mcpServers": {
"metabase-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/metabase-mcp",
"python",
"server.py"
],
"env": {
"METABASE_URL": "https://your-metabase-instance.com",
"METABASE_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Option 3: Using FastMCP CLI
```bash
fastmcp install server.py -n "Metabase MCP"
```
## 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_mongodb_query` | Execute native MongoDB queries with automatic JSON conversion for aggregation pipelines |
| `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 |
| `create_mongodb_card` | Create new MongoDB questions/cards with native query support |
### 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
├── pyproject.toml # Project configuration and dependencies
└── .env.example # Environment variables template
```
## 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
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
markitdown
Python tool for converting files and office documents to Markdown.
firecrawl
Firecrawl MCP Server enables web scraping, crawling, and content extraction.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
TrendRadar
TrendRadar: Your hotspot assistant for real news in just 30 seconds.
mempalace
The highest-scoring AI memory system ever benchmarked. And it's free.