MCP Server ODBC via SQLAlchemy

---

通过 SQLAlchemy 使用 ODBC 的 MCP 服务

一个使用 FastAPI、pyodbc 和 SQLAlchemy 构建的轻量级 ODBC MCP（Model Context Protocol）服务。该服务兼容 Virtuoso DBMS 以及其他实现了 SQLAlchemy provider 的 DBMS 后端。

---

功能特性

• 获取 Schema：从已连接的数据库中获取并列出所有 schema 名称。
• 获取表：检索指定 schema 或所有 schema 的表信息。
• 描述表：生成表结构的详细描述，包括：
  • 列名和数据类型
  • 可空属性
  • 主键和外键
• 搜索表：根据名称子字符串筛选并检索表。
• 执行存储过程：在 Virtuoso 的情况下，执行存储过程并检索结果。
• 执行查询：
  • JSONL 结果格式：针对结构化响应进行优化。
  • Markdown 表格格式：适用于报告和可视化。

---

前提条件

1. 安装 uv：

   pip install uv
   

   或使用 Homebrew：

   brew install uv
   

2. unixODBC 运行时环境检查：

3. 通过运行以下命令检查安装配置（即关键 INI 文件的位置）：odbcinst -j

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 示例。

Database	URL Format
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
podbc_get_schemas	列出已连接的数据库管理系统（DBMS）可访问的数据库 schema。
podbc_get_tables	列出与所选数据库 schema 关联的表。
podbc_describe_table	提供与指定数据库 schema 关联的表的描述。这包括列名、数据类型、空值处理、自增、主键和外键等信息
podbc_filter_table_names	根据 q 输入字段中的子字符串模式，列出与所选数据库 schema 关联的表。
podbc_query_database	执行 SQL 查询并以 JSONL 格式返回结果。
podbc_execute_query	执行 SQL 查询并以 JSONL 格式返回结果。
podbc_execute_query_md	执行 SQL 查询并以 Markdown 表格格式返回结果。
podbc_spasql_query	执行 SPASQL 查询并返回结果。
podbc_sparql_query	执行 SPARQL 查询并返回结果。
podbc_virtuoso_support_ai	与 Virtuoso Support Assistant/Agent 交互——这是 Virtuoso 特有的用于与大模型交互的功能

详细描述

• podbc_get_schemas

  • 检索并返回已连接数据库中所有 schema 名称的列表。
  • 输入参数：
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 返回 schema 名称的 JSON 字符串数组。

• podbc_get_tables

  • 检索并返回包含指定 schema 中表信息的列表。如果未提供 schema，则使用连接的默认 schema。
  • 输入参数：
    • schema（字符串，可选）：用于筛选表的数据库 schema。默认为连接的默认值。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 返回包含表信息的 JSON 字符串（例如 TABLE_CAT、TABLE_SCHEM、TABLE_NAME、TABLE_TYPE）。

• podbc_filter_table_names

  • 筛选并返回名称包含指定子字符串的表信息。
  • 输入参数：
    • q（字符串，必填）：要在表名称中搜索的子字符串。
    • schema（字符串，可选）：用于筛选表的数据库 schema。默认为连接的默认值。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 返回包含匹配表信息的 JSON 字符串。

• podbc_describe_table

  • 检索并返回指定表的列的详细信息。
  • 输入参数：
    • schema（字符串，必填）：包含该表的数据库 schema 名称。
    • table（字符串，必填）：要描述的表名称。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 返回描述表列的 JSON 字符串（例如 COLUMN_NAME、TYPE_NAME、COLUMN_SIZE、IS_NULLABLE）。

• podbc_query_database

  • 执行标准 SQL 查询并以 JSON 格式返回结果。
  • 输入参数：
    • query（字符串，必填）：要执行的 SQL 查询字符串。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 以 JSON 字符串形式返回查询结果。

• podbc_query_database_md

  • 执行标准 SQL 查询并以 Markdown 表格格式返回结果。
  • 输入参数：
    • query（字符串，必填）：要执行的 SQL 查询字符串。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 以 Markdown 表格字符串形式返回查询结果。

• podbc_query_database_jsonl

  • 执行标准 SQL 查询并以 JSON Lines（JSONL）格式返回结果（每行一个 JSON 对象）。
  • 输入参数：
    • query（字符串，必填）：要执行的 SQL 查询字符串。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 以 JSONL 字符串形式返回查询结果。

• podbc_spasql_query

  • 执行 SPASQL（SQL/SPARQL 混合）查询并返回结果。这是 Virtuoso 特有的功能。
  • 输入参数：
    • query（字符串，必填）：SPASQL 查询字符串。
    • max_rows（数字，可选）：返回的最大行数。默认值为 20。
    • timeout（数字，可选）：查询超时时间（毫秒）。默认值为 30000。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 返回底层存储过程调用的结果（例如 Demo.demo.execute_spasql_query）。

• podbc_sparql_query

  • 执行 SPARQL 查询并返回结果。这是 Virtuoso 特有的功能。
  • 输入参数：
    • query（字符串，必填）：SPARQL 查询字符串。
    • format（字符串，可选）：期望的结果格式。默认值为 'json'。
    • timeout（数字，可选）：查询超时时间（毫秒）。默认值为 30000。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 返回底层函数调用的结果（例如 "UB".dba."sparqlQuery"）。

• podbc_virtuoso_support_ai

  • 利用 Virtuoso 特有的 AI 助手函数，传递提示词和可选的 API 密钥。这是 Virtuoso 特有的功能。
  • 输入参数：
    • prompt（字符串，必填）：用于 AI 函数的提示词文本。
    • api_key（字符串，可选）：AI 服务的 API 密钥。默认值为 "none"。
    • user（字符串，可选）：数据库用户名。默认值为 "demo"。
    • password（字符串，可选）：数据库密码。默认值为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认值为 "Local Virtuoso"。
  • 返回 AI 支持助手函数调用的结果（例如 DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI）。

---

故障排查

为便于故障排查：

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 以对服务交互进行故障排查。