MCP Alchemy

MCP炼金术

状态：工作良好，日常使用中没有任何已知的错误。

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

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

• 帮助您探索和理解数据库结构
• 协助编写和验证SQL查询
• 显示表之间的关系
• 分析大型数据集并创建报告
• Claude Desktop可以使用以下工具为非常大的数据集分析和创建工件 克劳德本地文件.

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

安装

确保您已安装紫外线：

# Install uv if you haven't already
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"
      }
    }
  }
}

甲骨文

{
  "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"
      }
    }
  }
}

板条箱DB

{
  "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：SQL炼金术 数据库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 （字符串） - 返回匹配的表名

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

• 模式定义

- 获取指定表的详细架构 - 输入： 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

- 特征： - 智能截断大结果 - 通过以下方式访问完整结果集 克劳德本地文件 整合 - 清除NULL值显示 - ISO格式日期 - 清晰的行分隔

克劳德本地文件

当 克劳德本地文件 已配置：

• 在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发送邮件不多 -Claude Desktop的电子邮件助手使用不多。
• Diffpilot 的 -带文件分组和标记的多列git diff查看器。
• 克劳德本地文件 -访问Claude Desktop工件中的本地文件。

MCP目录列表

MCP炼金术列在以下MCP目录站点和存储库中：

• PulseMCP
• 格拉玛
• MCP.so
• MCP档案
• 播放手册MCP
• 出色的MCP服务器

贡献

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

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

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

许可证

Mozilla公共许可证版本2.0