Metabase Hosted

A hosted MCP (Model Context Protocol) server that enables Claude to interact with Metabase. Users authenticate with their own Metabase API keys, allowing Claude to query databases, manage dashboards, and explore data on their behalf.

Features

• OAuth 2.0 Authentication: Secure authentication flow with PKCE support for Claude Teams
• Per-User API Keys: Each user connects their own Metabase API key, maintaining individual permissions
• Full Metabase API Coverage: 40+ tools for managing collections, dashboards, cards, databases, users, and groups
• SQL Query Execution: Run native SQL queries against connected databases
• Audit Logging: Track all operations for compliance and debugging

Available Tools

Collections

Tool	Description
get_collections	List all collections
get_collection	Get collection details
get_collection_items	List items in a collection
create_collection	Create a new collection
update_collection	Update collection name/description
delete_collection	Delete a collection

Cards/Questions

Tool	Description
get_cards	List all saved questions
get_card	Get question details
get_card_query_results	Execute a saved question
create_card	Create a new question
update_card	Update a question
delete_card	Delete a question
search_cards	Search questions by name

Dashboards

Tool	Description
get_dashboards	List all dashboards
get_dashboard	Get dashboard details
create_dashboard	Create a new dashboard
update_dashboard	Update dashboard name/description
delete_dashboard	Delete a dashboard
copy_dashboard	Duplicate a dashboard
add_card_to_dashboard	Add a question to a dashboard
remove_card_from_dashboard	Remove a question from a dashboard

Databases

Tool	Description
get_databases	List all database connections
get_database	Get database details
get_database_metadata	Get tables and fields
get_database_tables	List tables in a database
get_table_fields	Get columns for a table
sync_database	Trigger schema sync

SQL Queries

Tool	Description
execute_sql_query	Run a native SQL query
get_query_results	Retrieve cached query results
search	Search across all Metabase entities

Users & Groups (Admin)

Tool	Description
get_current_user	Get authenticated user info
get_users	List all users
get_user	Get user details
create_user	Create a new user
update_user	Update user info
delete_user	Delete a user
get_groups	List permission groups
get_group	Get group details
create_group	Create a permission group
delete_group	Delete a permission group
add_user_to_group	Add user to a group
remove_user_from_group	Remove user from a group

Deployment

Prerequisites

• A Metabase instance with API access enabled
• A PostgreSQL database for storing credentials and OAuth state
• Railway, Render, or similar hosting platform

Deploy to Railway

1. Create a new Railway project or add to an existing one

2. Add a PostgreSQL database (if not already present)

3. Create a new service from this repository

4. Set environment variables:

DATABASE_URL=postgresql+asyncpg://${{Postgres.PGUSER}}:${{Postgres.PGPASSWORD}}@${{Postgres.PGHOST}}:${{Postgres.PGPORT}}/your_database
METABASE_URL=https://your-metabase-instance.com
ENCRYPTION_KEY=<generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())">
JWT_SECRET=<generate with: python -c "import secrets; print(secrets.token_urlsafe(32))">
BASE_URL=https://your-railway-service.up.railway.app

5. Generate a domain for the service

6. Deploy - Railway will automatically build and deploy

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string (asyncpg format)
METABASE_URL	Yes	Your Metabase instance URL (no trailing slash)
ENCRYPTION_KEY	Yes	Fernet key for encrypting stored API keys
JWT_SECRET	Yes	Secret for signing JWT tokens
BASE_URL	Yes	Public URL of this MCP server
JWT_ALGORITHM	No	JWT algorithm (default: HS256)
JWT_EXPIRE_MINUTES	No	Access token expiry (default: 60)
REFRESH_TOKEN_EXPIRE_DAYS	No	Refresh token expiry (default: 30)
RATE_LIMIT_PER_MINUTE	No	Rate limit per user (default: 100)
ALLOWED_REDIRECT_URIS	No	Comma-separated allowed OAuth redirect URIs

Configuration

Claude Teams

1. Go to Claude Teams Admin > Integrations > Add Integration

2. Select MCP Server

3. Configure the integration:

Field	Value
Name	Metabase
MCP Server URL	https://your-service.up.railway.app/mcp

4. Click Save

5. Team members will be prompted to connect when they first use Metabase tools

User Authentication Flow

When a user first interacts with Metabase through Claude:

1. Claude prompts to Connect to Metabase
2. User is redirected to the MCP server's authentication page
3. User enters their Metabase API key:
   • Log into Metabase
   • Go to Settings > Account Settings > API Keys
   • Click Create API Key and copy it
4. User pastes the API key and submits
5. User is redirected back to Claude, now authenticated

Individual Claude Users (Claude Pro/Free)

Individual Claude users can connect via the Claude desktop app or claude.ai with MCP support:

1. In Claude settings, add a new MCP server:

   • URL: https://your-service.up.railway.app/mcp

2. When prompted, complete the OAuth flow by entering your Metabase API key

Local Development

Setup

# Clone the repository
git clone https://github.com/your-org/metabase-hosted-mcp.git
cd metabase-hosted-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Copy environment template
cp .env.example .env
# Edit .env with your configuration

Running Locally

# Start the server
uvicorn app.main:app --reload --port 8000

# Or use the provided script
./run.sh

Database Migrations

The server uses Alembic for database migrations. Migrations run automatically on startup.

# Create a new migration
alembic revision --autogenerate -m "description"

# Run migrations manually
alembic upgrade head

API Endpoints

Endpoint	Method	Description
/	GET	Server info
/health	GET	Health check
/mcp	POST	MCP JSON-RPC endpoint
/oauth/register	POST	Dynamic client registration
/oauth/authorize	GET	Start OAuth flow
/oauth/token	POST	Token exchange
/oauth/revoke	POST	Revoke tokens
/auth/api-key	GET/POST	API key entry form
/.well-known/oauth-authorization-server	GET	OAuth metadata
/.well-known/oauth-protected-resource	GET	Protected resource metadata

Security

• API keys are encrypted at rest using Fernet symmetric encryption
• OAuth 2.0 with PKCE prevents authorization code interception
• Per-user isolation: Each user's requests use their own Metabase API key
• Audit logging tracks all tool invocations
• Rate limiting prevents abuse (configurable)

Example Prompts

Once connected, users can ask Claude:

"Show me all dashboards in Metabase"

"What databases are connected to Metabase?"

"Run this SQL query: SELECT COUNT(*) FROM orders WHERE created_at > '2024-01-01'"

"Create a new dashboard called 'Sales Overview' and add some charts"

"Search for any questions related to revenue"

"What tables are in the analytics database? Show me their columns."

Troubleshooting

"405 Method Not Allowed" on POST /

The MCP endpoint is /mcp, not /. Update your Claude integration URL to include /mcp:

• Wrong: https://your-service.up.railway.app/
• Correct: https://your-service.up.railway.app/mcp

"401 Unauthorized" when validating API key

• Ensure your Metabase API key is valid and not expired
• Check that METABASE_URL has no trailing slash
• Verify the API key has appropriate permissions in Metabase

OAuth flow completes but connection fails

• Verify BASE_URL matches your actual deployed URL
• Check that ALLOWED_REDIRECT_URIS includes Claude's callback URLs
• Ensure the PostgreSQL database is accessible

"Invalid or missing Bearer token"

• The OAuth token may have expired; reconnect through Claude
• Check that the JWT_SECRET hasn't changed since tokens were issued

Credits

Powered by:

• Metabase - Open source business intelligence
• Model Context Protocol (MCP) - Anthropic's protocol for AI tool integration
• FastAPI - Modern Python web framework
• Railway - Cloud deployment platform

License

MIT