metabase

This MCP server provides a comprehensive Metabase integration for AI assistants, exposing 81+ Metabase tools across dashboards, cards, databases, tables, and miscellaneous utilities. By running the server with the published package, you give your AI agent access to list, create, update, and delete dashboards and cards, manage database connections and schemas, execute queries (including pivot and formatted results), and interact with public links and embeddings. You can tailor which tools are loaded with flags like --all, --write, or --read, and you can run either the published package or a local build for development.

To use it, configure the environment with your Metabase instance details (URL and API key, or username/password fallback). Then start the server via npx, npm run build and node dist/server.js for local development, or run via Docker. The server will expose a set of MCP endpoints that your AI agent can invoke to perform Metabase operations within the connected Metabase environment.

Prerequisites:

• Node.js v14+ (recommended v20.x) and npm/yarn
• Access to the internet to install the MCP server package

Method 1: Running with NPX (recommended)

1. Install and run with NPX in one step:

export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @cognitionai/metabase-mcp-server

Method 2: Global installation (alternative)

npm install -g @cognitionai/metabase-mcp-server
metabase-mcp-server

Method 3: Development / Local build

1. Install dependencies and build:

npm install
npm run build

2. Run the built server from dist:

export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
node dist/server.js                    # Default (essential tools)
node dist/server.js --all             # All tools
node dist/server.js --write           # Write tools only
node dist/server.js --read            # Read-only tools only

Method 4: Docker (recommended for containerized deployments)

docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  ghcr.io/CognitionAI/metabase-mcp-server

Environment variables:

• METABASE_URL: Required for connecting to Metabase.
• METABASE_API_KEY or METABASE_USERNAME/METABASE_PASSWORD: Choose API key authentication (preferred) or username/password fallback. If using username/password, supply METABASE_USERNAME and METABASE_PASSWORD in addition to METABASE_URL.

Tool loading flags:

• --essential (default): load core essential tools
• --all: load all 80+ tools
• --write: load only write/modification tools
• --read: load only read-only tools

Troubleshooting:

• Ensure your Metabase instance is reachable from the MCP server host.
• Verify API keys or credentials have the necessary permissions for requested operations.
• If using local builds, ensure the dist/server.js path is correct.
• When running in Docker, ensure environment variables are passed correctly and that network access to Metabase is allowed.

Security:

• Do not expose METABASE_URL and API keys in client-side configs. Treat them as sensitive server-side configuration.