MCP Alchemy

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

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

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

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

支持PostgreSQL、MySQL、MariaDB、SQLite、Oracle、MS SQL Server、CrateDB、Vertica以及许多其他SQLAlchemy兼容的数据库。

安装

确保已安装uv：

# 如果尚未安装uv，请安装
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==2025.8.15.91819",
               "--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==2025.8.15.91819", "--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==2025.8.15.91819", "--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==2025.8.15.91819", "--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==2025.8.15.91819", "--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==2025.8.15.91819", "--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:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true。

Vertica

{
  "mcpServers": {
    "my_vertica_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--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}}"
      }
    }
  }
}

环境变量

• 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（字符串）
  • 返回匹配的表名

  输入: "user"
  返回: "users, user_roles, user_permissions"
  

• schema_definitions

  • 获取指定表的详细模式
  • 输入：table_names（字符串[]）
  • 返回表定义，包括：
    • 列名和类型
    • 主键
    • 外键关系
    • 可为空标志

  users:
      id: INTEGER, 主键, 自增
      email: VARCHAR(255), 可为空
      created_at: DATETIME
      
      关系:
        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设置时，集成会自动激活。

开发

首先克隆github仓库，安装依赖和你选择的数据库驱动：

git clone git@github.com: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电子邮件助手。
• Diffpilot - 多列git diff查看器，支持文件分组和标记。
• Claude Local Files - 在Claude Desktop工件中访问本地文件。

MCP目录列表

MCP Alchemy在以下MCP目录站点和仓库中列出：

• PulseMCP
• Glama
• MCP.so
• MCP Archive
• Playbooks MCP
• Awesome MCP Servers

贡献

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

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

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

许可证

Mozilla 公共许可证 2.0 版