MCP Alchemy

状态： 运行良好，日常使用无已知错误。

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

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

• 帮助您探索和理解数据库结构
• 协助编写和验证SQL查询
• 显示表之间的关系
• 分析大型数据集并创建报告
• Claude桌面可以分析并创建大型数据集的工件，使用 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桌面中使用

添加到您的 claude_desktop_config.json。您需要在 --with 参数中添加适当的数据库驱动。

注意：在新版本发布后，可能会有长达600秒的本地缓存清除时间， 导致uv引发版本错误。重新启动MCP客户端即可解决该错误。

SQLite（Python内置）

{
  "mcpServers": {
    "my_sqlite_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.7.9.172934",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "sqlite:////绝对路径/to/database.db"
      }
    }
  }
}

PostgreSQL

{
  "mcpServers": {
    "my_postgres_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.7.9.172934", "--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.7.9.172934", "--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.7.9.172934", "--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.7.9.172934", "--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.7.9.172934", "--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.7.9.172934", "--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, primary key, autoincrement
      email: VARCHAR(255), nullable
      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桌面管理您的Redmine项目和问题。
• MCP Notmuch Sendmail - 使用notmuch的Claude桌面邮件助手。
• Diffpilot - 多列git差异查看器，支持文件分组和标记。
• Claude Local Files - 在Claude桌面工件中访问本地文件。

MCP目录列表

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

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

贡献

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

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

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

许可证

Mozilla公共许可证版本2.0