npm package: @holtweb/mcp-metabase
Description: MCP server for Metabase - Create dashboards and visualizations programmatically via Model Context Protocol
Author: HoltWeb
Latest version: 1.0.2

# @holtweb/mcp-metabase

[![npm version](https://badge.fury.io/js/@holtweb%2Fmcp-metabase.svg)](https://www.npmjs.com/package/@holtweb/mcp-metabase)
[![CI](https://github.com/vochub-tech/metabase.mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vochub-tech/metabase.mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP (Model Context Protocol) server for Metabase - Create dashboards and visualizations programmatically.

## Features

- 🚀 **Easy Setup**: Run with npx, no installation required
- 📊 **Full Metabase API**: Create dashboards, cards, and visualizations
- 🤖 **AI-Ready**: Works with Claude Desktop and other MCP clients
- 📈 **Business Intelligence**: Built-in support for KPIs, trends, and analytics
- 🎨 **Flexible**: Works with any Metabase instance and database

## Quick Start

### Using npx (no installation)

```bash
npx @holtweb/mcp-metabase \
  --url https://your-metabase.com \
  --api-key mb_your_api_key
```

### With Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@holtweb/mcp-metabase"],
      "env": {
        "METABASE_URL": "https://your-metabase.com",
        "METABASE_API_KEY": "mb_your_api_key",
        "METABASE_DATABASE_ID": "2",
        "METABASE_COLLECTION_ID": "8"
      }
    }
  }
}
```

## Installation (Optional)

If you prefer to install globally:

```bash
npm install -g @holtweb/mcp-metabase
```

Then run:

```bash
mcp-metabase --url https://your-metabase.com --api-key mb_xxx
```

## Configuration

### Command Line Options

```bash
npx @holtweb/mcp-metabase [options]

Options:
  --url <url>              Metabase URL (required)
  --api-key <key>          Metabase API key (required)
  --database-id <id>       Database ID (optional, uses env var if set)
  --collection-id <id>     Collection ID (optional, uses env var if set)
  --help                   Show help message
```

### Environment Variables

You can also use environment variables:

```bash
METABASE_URL=https://your-metabase.com \
METABASE_API_KEY=mb_your_api_key \
METABASE_DATABASE_ID=2 \
METABASE_COLLECTION_ID=8 \
npx @holtweb/mcp-metabase
```

## Available MCP Tools

Once connected, the following tools are available:

### Connection Management
- `metabase_test_connection` - Verify connectivity to Metabase
- `metabase_list_databases` - List available databases
- `metabase_list_collections` - List available collections

### Dashboard Operations
- `metabase_create_dashboard` - Create an empty dashboard
- `metabase_create_dashboard_with_cards` - Create dashboard with multiple cards
- `metabase_get_dashboard` - Fetch dashboard details
- `metabase_delete_dashboard` - Delete a dashboard

### Card Operations
- `metabase_create_card` - Create a visualization card
- `metabase_delete_card` - Delete a card

### Automation
- `metabase_quick_dashboard` - Create a simple dashboard quickly
- `metabase_auto_dashboard_from_schema` - Auto-generate dashboard from table schema

## Example Usage with Claude

Once configured, you can ask Claude to:

- "Create a sales dashboard with revenue trends"
- "Show me the top customers by revenue"
- "Build an executive dashboard with KPIs"
- "Create a chart showing monthly growth"
- "Generate a dashboard from my orders table"

## Getting Your Metabase API Key

1. Log into your Metabase instance as an admin
2. Go to Settings → Admin → People
3. Select your user account
4. Under "API Keys", click "Create API Key"
5. Copy the key (it starts with `mb_`)

## Finding Database and Collection IDs

### Database ID
1. Go to Settings → Admin → Databases
2. Click on your database
3. The ID is in the URL: `/admin/databases/{id}`

### Collection ID
1. Navigate to any collection
2. The ID is in the URL: `/collection/{id}`

## Troubleshooting

### Connection Issues
- Verify your Metabase URL (include https://)
- Check API key is valid and starts with `mb_`
- Ensure your user has necessary permissions

### MCP Client Issues
- Restart Claude Desktop after configuration changes
- Check logs in Claude Desktop developer console
- Verify the command runs successfully in terminal first

## Development

### Building from Source

```bash
git clone https://github.com/vochub-tech/metabase.mcp.git
cd metabase.mcp
pnpm install
pnpm build
```

### Running Locally

```bash
# Development mode (TypeScript)
pnpm dev

# Production mode (compiled)
node dist/cli.js --url https://metabase.com --api-key mb_xxx
```

## API Documentation

### Creating a Dashboard with Cards

```typescript
// Tool: metabase_create_dashboard_with_cards
{
  "name": "Sales Dashboard",
  "description": "Monthly sales metrics",
  "cards": [
    {
      "name": "Total Revenue",
      "sql": "SELECT SUM(amount) as revenue FROM orders",
      "display": "scalar",
      "layout": { "row": 0, "col": 0, "size_x": 4, "size_y": 3 }
    },
    {
      "name": "Revenue Trend",
      "sql": "SELECT date, SUM(amount) FROM orders GROUP BY date",
      "display": "line",
      "layout": { "row": 0, "col": 4, "size_x": 8, "size_y": 6 }
    }
  ]
}
```

### Visualization Types

- `scalar` - Single number KPI
- `bar` - Bar chart
- `line` - Line chart
- `area` - Area chart
- `pie` - Pie chart
- `table` - Data table
- `gauge` - Gauge chart
- `progress` - Progress bar

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and feature requests, please use the [GitHub issues page](https://github.com/vochub-tech/metabase.mcp/issues).

## Author

HoltWeb

---

Made with ❤️ for the MCP ecosystem