mcp-alchemy

🚀 MCP Alchemy 项目文档

MCP Alchemy 是一款强大的工具，旨在增强 Claude Desktop 与数据库的交互能力。借助该工具，Claude 能够直接访问和操作各类数据库，并获取相关数据信息。

🚀 快速开始

MCP Alchemy 可让 Claude 直接与数据库交互，获取所需数据信息。下面为你介绍其安装与使用的基本步骤。

📦 安装指南

克隆仓库

git clone git@github.com:runekaagaard/mcp-alchemy.git
cd mcp-alchemy
uv sync

安装依赖

按需安装数据库驱动：

uv pip install psycopg2-binary

配置Claude Desktop

将以下内容添加到 claude_desktop_config.json 中：

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

✨ 主要特性

工具（Tools）

• all_table_names
  • 功能：获取数据库中所有表的名称。
  • 输入：无
  • 输出：逗号分隔的表名列表。

  users, orders, products, categories
  

• filter_table_names
  • 功能：根据子字符串查找表。
  • 输入：q（字符串）
  • 输出：匹配的表名。

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

• schema_definitions
  • 功能：获取指定表的详细架构信息。
  • 输入：table_names（字符串数组）
  • 输出：包括列名称、类型、主键、外键关系和可空标志等表定义。

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

• execute_query
  • 功能：执行 SQL 查询并以垂直格式输出结果。
  • 输入：query（字符串）、可选的 params（对象）
  • 输出：整洁的垂直格式结果，支持大结果集的智能截断和完整的上下文窗口外数据访问。

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

环境变量（Environment Variables）

• DB_URL：SQLAlchemy 数据库 URL（必填）。
• CLAUDE_LOCAL_FILES_PATH：完整结果集的目录路径（可选）。
• EXECUTE_QUERY_MAX_CHARS：最大输出长度（可选，默认 4000）。

📄 API 文档

MCP Alchemy 提供了一系列 API 接口，方便开发者调用数据库功能。主要接口包括：

• 列出所有表名 (all_table_names)
• 过滤表名 (filter_table_names)
• 获取表架构信息 (schema_definitions)
• 执行查询 (execute_query)

📚 详细文档

与Claude Local Files 的集成

当配置了 claude-local-files 后，MCP Alchemy 可以：

• 访问上下文窗口外的大结果集。
• 生成详细的报告和可视化图表。
• 执行深度数据分析。
• 导出结果进行进一步处理。

开发指南

1. 克隆仓库：git clone git@github.com:runekaagaard/mcp-alchemy.git
2. 安装依赖：运行 uv sync 和必要的数据库驱动安装命令。
3. 配置Claude Desktop：参考上述配置示例，将 MCP Alchemy 集成到 Claude 中。

贡献指南

欢迎社区贡献！无论是报告问题、提出新功能、改进文档还是代码贡献，我们都热烈欢迎：

• 提交问题或功能请求
• 提交 Pull Request 修复 bug 或新增功能
• 增强文档或分享使用案例
• 在 GitHub 上讨论和交流经验

📄 许可证

项目采用 Mozilla Public License Version 2.0。

👨‍💻 作者的其他LLM 项目

• MCP Redmine：Claude Desktop 管理 Redmine 项目和任务。
• MCP Notmuch Sendmail：Claude Desktop 集成 Notmuch 邮件系统。
• MCP Alchemy：Claude Desktop 数据库交互工具。

希望以上文档能帮助您更好地理解和使用 MCP Alchemy 项目！