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

GitHub Container Registry 上发布了一个容器镜像，预装了常用数据库驱动程序 （PostgreSQL、MySQL/MariaDB、MS SQL Server、Oracle）：

{
  "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 . 自行构建。

传输方式

默认情况下，服务通过标准输入输出进行通信。它也可以通过 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 服务通常一次处理一个请求）
• 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 (string)
  • 返回匹配的表名

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

• schema_definitions

  • 获取指定表的详细架构
  • 输入：table_names (string[])
  • 返回表定义，包括：
    • 列名和类型
    • 主键
    • 外键关系
    • 可空标志

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

• execute_query

  • 以纵向输出格式执行 SQL 查询
  • 输入：
    • query (string)：SQL 查询
    • params (object, optional)：查询参数
  • 以简洁的纵向格式返回结果：

  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 差异查看器。
• 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