用途
MCP Alchemy 是一个 MCP（模型上下文协议）服务器，为 LLM 提供对关系型数据库的访问与相关知识。它让 Claude Desktop 等客户端可以直接连接数据库，充当数据库专家，协助探索并理解数据库结构、编写和验证 SQL 查询、展示表之间的关系、分析大型数据集并创建报告。项目处于活跃维护中并每日使用，测试版本会以 git 标签发布到 PyPI。
支持的数据库
支持 PostgreSQL、MySQL、MariaDB、SQLite、Oracle、MS SQL Server、CrateDB、Vertica，以及大量其他 SQLAlchemy 兼容的数据库。SQLite 驱动内置于 Python，无需额外安装。
安装与配置
需要先安装 uv。使用 Claude Desktop 时，将配置添加到 claude_desktop_config.json 中，并在 --with 参数里添加相应的数据库驱动。例如 SQLite（内置于 Python）和 Microsoft SQL Server 有各自的配置示例。连接 CrateDB Cloud 可使用形如 crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true 的 URL。
发布了容器镜像到 GitHub Container Registry，预装了常见数据库驱动（PostgreSQL、MySQL/MariaDB、MS SQL Server、Oracle），也可以用 docker build -t ghcr.io/runekaagaard/mcp-alchemy . 自行构建。
默认情况下服务器使用 stdio 通信，也可通过 HTTP 为相应客户端提供服务。
注意：新版本发布后可能有最多 600 秒的时间，本地缓存清除会导致 uv 报版本错误，再次重启 MCP 客户端即可解决。
环境变量
- 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 覆盖。对于超时设置较激进（如 MySQL 默认 8 小时）的数据库，pool_pre_ping 与 pool_recycle 的组合可确保连接可靠。
主要工具
- all_table_names：返回数据库中所有表名，无需输入，返回逗号分隔的表列表。
- filter_table_names：查找匹配子串的表，输入 q（字符串），返回匹配的表名。
- schema_definitions：获取指定表的详细模式，输入 table_names（字符串数组），返回表定义，包括列名和类型、主键、外键关系、可空标志。
- execute_query：执行 SQL 查询并以垂直输出格式返回结果。输入 query（字符串）和可选的 params（对象）。特性包括：对大结果智能截断、通过 claude-local-files 集成访问完整结果集、清晰的 NULL 值显示、ISO 格式日期、明确的行分隔。
Claude Local Files 集成
当配置了 CLAUDE_LOCAL_FILES_PATH 时，可以访问超出 Claude 上下文窗口的完整结果集，生成详细报告和可视化，对大型数据集进行深度分析，导出结果以供进一步处理。设置该环境变量后集成自动激活。
从源码运行
先克隆 GitHub 仓库，安装依赖和所选数据库驱动，然后在 claude_desktop_config.json 中进行相应设置。
许可证
Mozilla Public License Version 2.0。
欢迎贡献：报告 bug、提出功能请求、改进文档或提交代码，均可通过发起 issue 或 pull request 参与。
