Metabase MCP Server

Metabase MCP サーバー - AI アシスタントを Metabase の分析に接続

Metabase 向けの高性能な Model Context Protocol（MCP）サーバーです。Claude、Cursor などの AI アシスタントやその他の MCP クライアントが、Metabase インスタンスとシームレスに連携できるようにします。データベースへのクエリ、SQL の実行、ダッシュボードの管理、分析ワークフローの自動化を、AI を活用したデータベース操作を通じて自然言語で行えます。

最適な対象： Metabase のビジネスインテリジェンスプラットフォームに AI アシスタントを統合して、SQL クエリ、ダッシュボード管理、データ探索を自動化したいデータアナリスト、開発者、チーム。

主な機能

データベース操作

• データベース一覧：設定済みの Metabase データベースをすべて表示します
• テーブルの検出：メタデータと説明を含むテーブルを確認します
• フィールドの調査：スマートページネーションを使用してフィールド／列の詳細情報を取得します

クエリと分析

• SQL の実行：パラメーターとテンプレートに対応したネイティブ SQL クエリを実行します
• MongoDB のサポート：集約パイプライン用の自動 JSON 変換に対応して、ネイティブ MongoDB クエリを実行します
• カード管理：Metabase の質問／カード（SQL および MongoDB）を実行、作成、管理します
• コレクションの整理：整理しやすいようにコレクションを作成、管理します
• 自然言語クエリ：AI アシスタントが質問を SQL または MongoDB クエリに変換します

認証とセキュリティ

• API キーのサポート：Metabase API キーによる安全な認証（推奨）
• セッションベース認証：メールアドレス／パスワードによる代替認証
• 環境変数：.env ファイルを使用した安全な認証情報の管理

AI アシスタントとの連携

• Claude Desktop：Anthropic の Claude AI とのネイティブ連携
• Cursor IDE：AI 支援開発のためのシームレスな連携
• あらゆる MCP クライアント：すべての Model Context Protocol クライアントと互換性があります

パフォーマンスと信頼性の向上

• コンテキストを考慮したログ記録：デバッグ、情報、警告、エラーレベルのログをリアルタイムで記録し、AI クライアントから確認できます
• 適切なエラー処理：FastMCP の ToolError 例外により、エラーメッセージとデバッグを改善します
• ミドルウェアスタック：本番環境での信頼性を高める、組み込みのエラー処理およびログ記録ミドルウェア
• ベストプラクティス：重複の防止とクリーンな設定を実現する、最新の FastMCP パターンに準拠しています
• モダンな Python：Python 3.12+ の型ヒント（| 構文）を使用し、型安全性を高めます

クイックスタート

前提条件

• Python 3.12+
• API アクセスが可能な Metabase インスタンス
• uvx または uv パッケージマネージャー

インストール

オプション 1：uvx を使用（最も簡単 - インストール不要）

# 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

オプション 2：PyPI からインストール

# Install globally
uv tool install metabase-mcp

# Or with pip
pip install metabase-mcp

# Then run
metabase-mcp

オプション 3：開発環境のセットアップ（ソースから）

# 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

設定

Metabase の認証情報を記載した .env ファイルを作成します：

cp .env.example .env

設定オプション

オプション 1：API キー認証（推奨）

METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-here

オプション 2：メールアドレス／パスワード認証

METABASE_URL=https://your-metabase-instance.com
[email protected]
METABASE_PASSWORD=your-password

任意：Metabase API の HTTP タイムアウト

METABASE_HTTP_TIMEOUT=30.0  # Default: 30.0 seconds

任意：SSE／HTTP 用のカスタムホスト／ポート

HOST=localhost  # Default: 0.0.0.0
PORT=9000      # Default: 8000

使用方法

サーバーの実行

クイックスタート（セットアップ不要）

# 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

ソースから実行（開発）

# 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 との連携

Cursor の設定を編集して、手動で Cursor を設定できます。

SSE トランスポートの場合：Cursor を使用する前にサーバーを起動する必要があります：

uv run python server.py --sse

Claude Desktop との連携

オプション 1：uvx を使用（推奨）

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uvx",
            "args": ["metabase-mcp"],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

オプション 2：ローカルインストールを使用する

リポジトリをクローンした場合：

{
    "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"
            }
        }
    }
}

オプション 3：FastMCP CLI を使用する

fastmcp install server.py -n "Metabase MCP"

利用可能なツール

データベース操作

ツール	説明
list_databases	Metabase で設定されているすべてのデータベースを一覧表示します
list_tables	特定のデータベース内のすべてのテーブルとメタデータを取得します
get_table_fields	テーブルのフィールド／列情報を取得します

クエリ操作

ツール	説明
execute_query	パラメーターに対応したネイティブ SQL クエリを実行します
execute_mongodb_query	集計パイプラインの JSON を自動変換して、ネイティブ MongoDB クエリを実行します
execute_card	保存済みの Metabase の質問／カードを実行します

カード管理

ツール	説明
list_cards	保存済みのすべての質問／カードを一覧表示します
create_card	SQL クエリを使用して新しい質問／カードを作成します
create_mongodb_card	ネイティブクエリに対応した新しい MongoDB の質問／カードを作成します

コレクション管理

ツール	説明
list_collections	すべてのコレクションを表示します
create_collection	整理用の新しいコレクションを作成します

トランスポート方式

サーバーは複数のトランスポート方式に対応しています。

• STDIO（デフォルト）：IDE との連携用（Cursor、Claude Desktop）
• SSE：Web アプリケーション向けの Server-Sent Events
• HTTP：API アクセス用の標準 HTTP

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

開発

開発環境のセットアップ

# Install with dev dependencies
uv sync --group dev

# Or with pip
pip install -r requirements-dev.txt

コード品質

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy server.py

使用例

クエリの例

# 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
)

プロジェクト構成

metabase-mcp/
├── server.py                 # Main MCP server implementation
├── pyproject.toml           # Project configuration and dependencies
└── .env.example             # Environment variables template

貢献

皆さまからの貢献を歓迎します！お気軽に Pull Request を送信してください。

ライセンス

MIT License の詳細については、LICENSE ファイルをご覧ください。

リソース

• FastMCP のドキュメント
• Model Context Protocol
• Metabase API のドキュメント
• Claude Desktop のドキュメント
• Cursor IDE

キーワードとトピック

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

スター履歴

このプロジェクトが役に立った場合は、ぜひスターを付けてください！ほかの人がこのツールを見つけやすくなります。

ユースケース

• 自然言語によるデータベースクエリ：平易な英語で Claude に Metabase のデータベースをクエリするよう依頼します
• レポートの自動生成：AI を使用して Metabase のカードやコレクションを作成、管理します
• データ探索：AI アシスタントを活用して、データからインサイトを発見します
• SQL クエリの支援：AI を通じて SQL クエリの作成や最適化を支援してもらいます
• ダッシュボード管理：Metabase ダッシュボードの作成と整理を自動化します
• データ分析ワークフロー：AI を活用した分析を開発ワークフローに統合します