通过 SQLAlchemy 实现 MCP Server ODBC

一个轻量级的 MCP (模型上下文协议) 服务器，用于 ODBC，使用 FastAPI、pyodbc 和 SQLAlchemy 构建。此服务器与 Virtuoso DBMS 以及其他实现了 SQLAlchemy 提供程序的 DBMS 后端兼容。

---

功能

• 获取模式 (Schemas): 从连接的数据库中获取并列出所有模式名称。
• 获取表 (Tables): 检索特定模式或所有模式的表信息。
• 描述表 (Describe Table): 生成表结构的详细描述，包括：
  • 列名和数据类型
  • 可空属性
  • 主键和外键
• 搜索表 (Search Tables): 基于名称子字符串过滤和检索表。
• 执行存储过程 (Execute Stored Procedures): 在 Virtuoso 的情况下，执行存储过程并检索结果。
• 执行查询 (Execute Queries):
  • JSONL 结果格式：针对结构化响应进行了优化。
  • Markdown 表格格式：非常适合报告和可视化。

---

前提条件

1. 安装 uv:

   pip install uv
   

   或者使用 Homebrew:

   brew install uv
   

2. unixODBC 运行时环境检查:

3. 通过运行 odbcinst -j 检查安装配置（即，关键 INI 文件的位置）。

4. 通过运行 odbcinst -q -s 列出可用的数据源名称。

5. ODBC DSN 设置: 为目标数据库配置您的 ODBC 数据源名称 (~/.odbc.ini)。 Virtuoso DBMS 示例：

   [VOS]
   Description = OpenLink Virtuoso
   Driver = /path/to/virtodbcu_r.so
   Database = Demo
   Address = localhost:1111
   WideAsUTF16 = Yes
   

6. SQLAlchemy URL 绑定: 使用以下格式：

   virtuoso+pyodbc://user:password@VOS
   

---

安装

克隆此存储库：

git clone https://github.com/OpenLinkSoftware/mcp-sqlalchemy-server.git
cd mcp-sqlalchemy-server

环境变量

通过覆盖默认值来更新您的 .env 以匹配您的偏好

ODBC_DSN=VOS
ODBC_USER=dba
ODBC_PASSWORD=dba
API_KEY=xxx

---

配置

对于 Claude Desktop 用户： 将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "my_database": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-sqlalchemy-server", "run", "mcp-sqlalchemy-server"],
      "env": {
        "ODBC_DSN": "dsn_name",
        "ODBC_USER": "username",
        "ODBC_PASSWORD": "password",
        "API_KEY": "sk-xxx"
      }
    }
  }
}

---

用法

数据库管理系统 (DBMS) 连接 URL

以下是使用此 mcp-server 测试过的用于连接到 DBMS 系统的 pyodbc URL 示例。

数据库	URL 格式
Virtuoso DBMS	virtuoso+pyodbc://user:password@ODBC_DSN
PostgreSQL	postgresql://user:password@localhost/dbname
MySQL	mysql+pymysql://user:password@localhost/dbname
SQLite	sqlite:///path/to/database.db
连接后，您可以通过 Claude 与您的 WhatsApp 联系人互动，在您的 WhatsApp 对话中利用 Claude 的 AI 功能。

提供的工具

name	description
get_schemas	列出连接的数据库管理系统 (DBMS) 可访问的数据库模式。
get_tables	列出与选定的数据库模式关联的表。
describe_table	提供与指定数据库模式关联的表的描述。 这包括有关列名、数据类型、null 处理、自动递增、主键和外键的信息
filter_table_names	列出表，基于来自 q 输入字段的子字符串模式，与选定的数据库模式关联。
query_database	执行 SQL 查询并以 JSONL 格式返回结果。
execute_query	执行 SQL 查询并以 JSONL 格式返回结果。
execute_query_md	执行 SQL 查询并以 Markdown 表格格式返回结果。
spasql_query	执行 SPASQL 查询并返回结果。
sparql_query	执行 SPARQL 查询并返回结果。
virtuoso_support_ai	与 Virtuoso 支持助手/代理交互——Virtuoso 的特定功能，用于与 LLM 交互

---

故障排除

为了更容易进行故障排除：

1. 安装 MCP Inspector：

   npm install -g @modelcontextprotocol/inspector
   

2. 启动 inspector：

   npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-sqlalchemy-server run mcp-sqlalchemy-server
   

访问提供的 URL 以对服务器交互进行故障排除。