# metabase-lite-mcp

An MCP (Model Context Protocol) server that lets AI agents interact with Metabase — search dashboards & cards, explore database metadata, and run read-only query previews.

## Use Case

Give your AI agent (Claude, Cursor, etc.) the ability to:

- **Search & read** saved questions (cards) and dashboards
- **Explore database schema** — list databases, tables, fields, and collections
- **Run query previews** — execute read-only SQL/Mongo queries with built-in safety validation (write operations are blocked before they ever reach Metabase)

This is useful for agents that need to understand your data, find existing reports, validate queries, or build new dashboards on your behalf.

## Prerequisites

- Node.js 18+
- A Metabase instance with API key access enabled
- A Metabase [API key](https://www.metabase.com/docs/latest/people-and-groups/api-keys) (inherits permissions from its group)

## Install

```bash
npm install -g metabase-lite-mcp
```

Or use directly with `npx` (no install needed) — see configuration below.

## Configuration

The server requires two environment variables:

| Variable | Description | Example |
|---|---|---|
| `METABASE_BASE_URL` | Your Metabase instance URL | `https://metabase.example.com` |
| `METABASE_API_KEY` | Metabase API key | `mb_xxxxxxxxxxxxxx` |

## Usage with Claude Code

Add to your `.mcp.json` (project-level or `~/.claude/.mcp.json` for global):

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-lite-mcp"],
      "env": {
        "METABASE_BASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "mb_xxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Usage with Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-lite-mcp"],
      "env": {
        "METABASE_BASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "mb_xxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|---|---|
| `get_configured_databases` | List all databases configured in Metabase |
| `get_database_metadata` | Get tables and fields for a specific database |
| `get_collections` | List all collections |
| `search_cards` | Search saved questions by name/text |
| `get_card` | Get full details of a saved question |
| `search_dashboards` | Search dashboards by name/text |
| `get_dashboard_full` | Get full dashboard with tabs, cards, and filters |
| `run_query_preview` | Execute a read-only query and return results |

## Safety

All queries are validated before being sent to Metabase:

- **SQL**: Blocks `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, `CREATE`, `GRANT`, `REVOKE`, `CALL`, `EXECUTE`, and multi-statement queries
- **MongoDB**: Blocks `$out` and `$merge` pipeline stages

## Development

```bash
git clone https://github.com/sanjeevsingla/metabase-lite-mcp.git
cd metabase-lite-mcp
npm install
npm run build
npm run watch      # Rebuild on changes
npm run inspector  # Launch MCP inspector to test tools interactively
```

## License

MIT