MCP Alchemy

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

状态2：我刚刚将该包添加到了 PyPI，并更新了使用说明。请报告任何问题 :)

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

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

支持 PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB 以及许多其他 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 参数中添加适当的数据库驱动程序。

SQLite (内置在 Python 中)

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

PostgreSQL

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

MySQL/MariaDB

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

Microsoft SQL Server

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

Oracle

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

CrateDB

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

对于连接到 CrateDB Cloud，请使用类似以下的 URL:
crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true。

环境变量

• DB_URL: SQLAlchemy 数据库 URL（必需）
• CLAUDE_LOCAL_FILES_PATH: 用于完整结果集的目录（可选）
• EXECUTE_QUERY_MAX_CHARS: 最大输出长度（可选，默认为 4000）

API

工具

• all_table_names

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

  users, orders, products, categories
  

• filter_table_names

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

  输入: "user"
  返回: "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. 行
  id: 123
  name: John Doe
  created_at: 2024-03-15T14:30:00
  email: NULL
  
  结果: 1 行
  

  • 特性:
    • 智能截断大结果
    • 通过 claude-local-files 集成访问完整结果集
    • 清晰显示 NULL 值
    • ISO 格式的日期
    • 清晰的行分隔

Claude Local Files

当配置了 claude-local-files 时:

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

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

贡献

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

• 打开问题报告错误或建议功能
• 提交带有改进的拉取请求
• 增强文档或分享您的使用示例
• 提问并分享您的经验

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

许可证

Mozilla Public License Version 2.0

我的其他 LLM 项目

• MCP Redmine - 让 Claude Desktop 管理您的 Redmine 项目和问题。
• MCP Notmuch Sendmail - 使用 notmuch 的 Claude Desktop 电子邮件助手。
• Diffpilot - 带文件分组和标记的多列 git diff 查看器。
• Claude Local Files - 在 Claude Desktop 工件中访问本地文件。