MCP Alchemy

MCP Alchemy

ステータス：活発にメンテナンスされ、日常的に使用されています。テスト済みのリリースは Git タグとともに PyPI で公開され、イシューとプルリクエストは定期的にトリアージされています。

Claude をデータベースのエキスパートにしましょう！MCP Alchemy は Claude Desktop をデータベースに直接接続し、次のことを可能にします。

• データベース構造の調査と理解を支援します
• SQL クエリの作成と検証を支援します
• テーブル間のリレーションシップを表示します
• 大規模なデータセットを分析し、レポートを作成します
• Claude Desktop は claude-local-files を使用して、非常に大規模なデータセットを分析し、アーティファクトを作成できます。

PostgreSQL、MySQL、MariaDB、SQLite、Oracle、MS SQL Server、CrateDB、Vertica、 およびその他多数の SQLAlchemy 互換データベースで動作します。

インストール

uv がインストールされていることを確認してください：

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Desktop での使用方法

claude_desktop_config.json に追加してください。--with パラメーターに適切なデータベースドライバーを指定する必要があります。

注：新しいバージョンのリリース後、キャッシュがクリアされるまで最大 600 秒かかる場合があります。その間、uv がバージョンエラーを発生させることがあります。MCP クライアントを再起動するとエラーは解消されます。

SQLite（Python に組み込み）

{
  "mcpServers": {
    "my_sqlite_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.10.15.202659",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "sqlite:////absolute/path/to/database.db"
      }
    }
  }
}

PostgreSQL

{
  "mcpServers": {
    "my_postgres_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.10.15.202659", "--with", "psycopg2-binary",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "postgresql://user:password@localhost/dbname"
      }
    }
  }
}

MySQL/MariaDB

{
  "mcpServers": {
    "my_mysql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.10.15.202659", "--with", "pymysql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mysql+pymysql://user:password@localhost/dbname"
      }
    }
  }
}

Microsoft SQL Server

{
  "mcpServers": {
    "my_mssql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.10.15.202659", "--with", "pymssql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mssql+pymssql://user:password@localhost/dbname"
      }
    }
  }
}

Oracle

{
  "mcpServers": {
    "my_oracle_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.10.15.202659", "--with", "oracledb",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "oracle+oracledb://user:password@localhost/dbname"
      }
    }
  }
}

CrateDB

{
  "mcpServers": {
    "my_cratedb": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.10.15.202659", "--with", "sqlalchemy-cratedb>=0.42.0.dev1",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "crate://user:password@localhost:4200/?schema=testdrive"
      }
    }
  }
}

CrateDB Cloud に接続するには、次のような URL を使用します。 crate://user:[email protected]:4200?ssl=true。

Vertica

{
  "mcpServers": {
    "my_vertica_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.10.15.202659", "--with", "vertica-python",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "vertica+vertica_python://user:password@localhost:5433/dbname",
        "DB_ENGINE_OPTIONS": "{\"connect_args\": {\"ssl\": false}}"
      }
    }
  }
}

Docker

一般的なデータベースドライバー（PostgreSQL、MySQL/MariaDB、MS SQL Server、Oracle）がプリインストールされたコンテナーイメージが、GitHub Container Registry に公開されています。

{
  "mcpServers": {
    "my_db": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DB_URL",
               "ghcr.io/runekaagaard/mcp-alchemy:latest"],
      "env": {
        "DB_URL": "postgresql://user:[email protected]/dbname"
      }
    }
  }
}

または、docker build -t ghcr.io/runekaagaard/mcp-alchemy . で自分でビルドしてください。

トランスポート

デフォルトでは、サーバーは stdio を使用します。同じ方式で接続するクライアント向けに、HTTP 経由でサービスを提供することもできます。

# Recommended HTTP transport (serves on http://HOST:PORT/mcp)
mcp-alchemy --transport streamable-http --host 127.0.0.1 --port 7000

# Legacy SSE transport, for older clients (serves on http://HOST:PORT/sse)
mcp-alchemy --transport sse --host 127.0.0.1 --port 7000

環境変数

• DB_URL：SQLAlchemy のデータベース URL（必須）
• CLAUDE_LOCAL_FILES_PATH：結果セット全体を保存するディレクトリ（任意）
• EXECUTE_QUERY_MAX_CHARS：出力の最大長（任意、デフォルトは 4000）
• DB_ENGINE_OPTIONS：追加の SQLAlchemy エンジンオプションを含む JSON 文字列（任意）

コネクションプーリング

MCP Alchemy は、長時間稼働する MCP サーバー向けに最適化されたコネクションプーリングを使用します。デフォルト設定は次のとおりです。

• pool_pre_ping=True：使用前に接続をテストし、データベースのタイムアウトやネットワークの問題に対処します
• pool_size=1：永続的な接続を 1 つ維持します（MCP サーバーは通常、一度に 1 件のリクエストを処理します）
• max_overflow=2：バースト時に最大 2 つの追加接続を許可します
• pool_recycle=3600：1 時間を超えた接続を更新します（タイムアウトの問題を防止します）
• isolation_level='AUTOCOMMIT'：各クエリが自動的にコミットされるようにします

これらのデフォルト設定はほとんどのデータベースで適切に機能しますが、DB_ENGINE_OPTIONS で上書きできます。

{
  "DB_ENGINE_OPTIONS": "{\"pool_size\": 5, \"max_overflow\": 10, \"pool_recycle\": 1800}"
}

MySQL のデフォルトの 8 時間など、タイムアウト設定が厳しいデータベースでは、pool_pre_ping と pool_recycle を組み合わせることで、安定した接続を確保できます。

API

ツール

• all_table_names

  • データベース内のすべてのテーブル名を返します
  • 入力は不要です
  • テーブル名をカンマ区切りのリストで返します

  users, orders, products, categories
  

• filter_table_names

  • 部分文字列に一致するテーブルを検索します
  • 入力：q（文字列）
  • 一致するテーブル名を返します

  Input: "user"
  Returns: "users, user_roles, user_permissions"
  

• schema_definitions

  • 指定したテーブルの詳細なスキーマを取得します
  • 入力：table_names（string[]）
  • 以下を含むテーブル定義を返します：
    • カラム名と型
    • 主キー
    • 外部キーの関係
    • NULL 許容フラグ

  users:
      id: INTEGER, primary key, autoincrement
      email: VARCHAR(255), nullable
      created_at: DATETIME
      
      Relationships:
        id -> orders.user_id
  

• execute_query

  • 縦形式で SQL クエリを実行します
  • 入力：
    • query（文字列）：SQL クエリ
    • params（オブジェクト、任意）：クエリパラメーター
  • 結果を見やすい縦形式で返します：

  1. row
  id: 123
  name: John Doe
  created_at: 2024-03-15T14:30:00
  email: NULL
  
  Result: 1 rows
  

  • 機能：
    • 大きな結果をスマートに省略表示
    • claude-local-files との連携により、結果セット全体にアクセス
    • NULL 値を見やすく表示
    • ISO 形式の日付
    • 行を明確に区切って表示

Claude Local Files

claude-local-files が設定されている場合：

• Claude のコンテキストウィンドウを超える結果セット全体にアクセスできます
• 詳細なレポートや可視化を生成できます
• 大規模なデータセットを詳細に分析できます
• さらなる処理のために結果をエクスポートできます

CLAUDE_LOCAL_FILES_PATH が設定されると、連携は自動的に有効になります。

開発

まず、github リポジトリをクローンし、依存関係と使用するデータベースドライバーをインストールします：

git clone [email protected]:runekaagaard/mcp-alchemy.git
cd mcp-alchemy
uv sync
uv pip install psycopg2-binary

次に、これを claude_desktop_config.json に設定します：

...
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-alchemy", "-m", "mcp_alchemy.server", "main"],
...

その他の LLM プロジェクト

• MCP Redmine - Claude Desktop で Redmine のプロジェクトや課題を管理できます。
• MCP Notmuch Sendmail - notmuch を使った Claude Desktop 用メールアシスタントです。
• MCP Show-on-Kindle - KOReader を実行している Kindle にファイルをコピーし、画面上で開きます。
• Diffpilot - ファイルのグループ化とタグ付けができる、複数列の git diff ビューアーです。
• Claude Local Files - Claude Desktop のアーティファクトからローカルファイルにアクセスできます。

MCP ディレクトリへの掲載

MCP Alchemy は、以下の MCP ディレクトリサイトおよびリポジトリに掲載されています：

• PulseMCP
• Glama
• MCP.so
• MCP Archive
• Playbooks MCP
• Awesome MCP Servers

貢献

貢献を心より歓迎します！バグ報告、機能リクエスト、ドキュメントの改善、コードの提供など、すべてのご意見が役立ちます。お気軽にどうぞ：

• バグの報告や機能の提案のために issue を作成する
• 改善のためのプルリクエストを送信する
• ドキュメントを充実させたり、使用例を共有したりする
• 質問したり、経験を共有したりする

目標は、Claude でのデータベース操作をさらに便利にすることです。皆様の知見や貢献が、その実現に役立ちます。

ライセンス

Mozilla Public License Version 2.0