MCP Alchemy

状态：运行良好，日常使用中，未发现任何已知错误。

状态 2：我目前正在努力将其发布到 PYPI，并寻找最用户友好的方式来使用 uvx 运行它，因此请注意安装说明在未来几周内可能会发生变化。

让 Claude 成为您的数据库专家！ MCP Alchemy 将 Claude Desktop 直接连接到您的数据库，使其能够：

• 帮助您探索和理解您的数据库结构
• 协助编写和验证 SQL 查询
• 显示表之间的关系
• 分析大型数据集并创建报告
• Claude Desktop 可以使用 claude-local-files 分析大型数据集并创建工件。

适用于 PostgreSQL、MySQL、MariaDB、SQLite、Oracle、MS SQL Server 以及许多其他 SQLAlchemy 兼容 的数据库。

API

工具

• all_table_names

  • 返回数据库中所有表名
  • 无需输入
  • 返回以逗号分隔的表列表

  users, orders, products, categories
  

• filter_table_names

  • 查找与子字符串匹配的表
  • 输入：q (字符串)
  • 返回匹配的表名

  Input: "user"
  Returns: "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 (字符串): 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 Desktop 一起使用

添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "my_database": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-alchemy", "run", "mcp_alchemy.py"],
      "env": {
        "DB_URL": "mysql+pymysql://root:secret@localhost/databasename",
      }
    }
  }
}

环境变量：

• DB_URL: SQLAlchemy 数据库 URL (必需) 示例：
  • PostgreSQL: postgresql://user:password@localhost/dbname
  • MySQL: mysql+pymysql://user:password@localhost/dbname
  • MariaDB: mariadb+pymysql://user:password@localhost/dbname
  • SQLite: sqlite:///path/to/database.db
• CLAUDE_LOCAL_FILES_PATH: 完整结果集的目录 (可选)
• EXECUTE_QUERY_MAX_CHARS: 最大输出长度 (可选, 默认 4000)

安装

1. 克隆存储库：

git clone https://github.com/runekaagaard/mcp-alchemy.git

2. 确保您已安装 uv

# 如果您尚未安装 uv，请安装它
curl -LsSf https://astral.sh/uv/install.sh | sh

3. 将数据库添加到 claude_desktop_config.json (见上文)

数据库驱动程序

默认情况下包含以下数据库驱动程序：

• SQLite：内置于 Python，无需额外安装
• MySQL/MariaDB：通过 pymysql
• PostgreSQL：通过 psycopg2-binary

要使用 SQLAlchemy 支持的其他数据库，请安装相应的驱动程序：

# Microsoft SQL Server
uv pip install pymssql

# Oracle
uv pip install cx_oracle

# 其他数据库
# 参见：https://docs.sqlalchemy.org/en/20/dialects/

Claude Local Files

当配置了 claude-local-files 时：

• 访问超出 Claude 上下文窗口的完整结果集
• 生成详细的报告和可视化
• 对大型数据集执行深入分析
• 导出结果以进行进一步处理

当设置了 CLAUDE_LOCAL_FILES_PATH 时，集成会自动激活。

贡献

热烈欢迎贡献！无论是错误报告、功能请求、文档改进还是代码贡献 - 所有输入都很有价值。请随意：

• 打开一个 issue 来报告错误或建议功能
• 提交包含改进的 pull request
• 增强文档或分享您的使用示例
• 提出问题并分享您的经验

目标是使与 Claude 的数据库交互更加出色，您的见解和贡献有助于实现这一目标。

许可证

Mozilla Public License Version 2.0