---

OpenLink MCP Server for ODBC via PyODBC

一个轻量级的MCP（模型上下文协议）服务器，用于ODBC，使用FastAPI和pyodbc构建。此服务器兼容Virtuoso DBMS以及任何具有ODBC驱动程序的其他数据库管理系统。

---

功能

• 获取模式：从连接的数据库中获取并列出所有模式名称。
• 获取表：检索特定模式或所有模式的表信息。
• 描述表：生成表结构的详细描述，包括：
  • 列名和数据类型
  • 可空属性
  • 主键和外键
• 搜索表：根据名称子串过滤并检索表。
• 执行存储过程：当连接到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
   

---

安装

克隆此仓库：

git clone https://github.com/OpenLinkSoftware/mcp-pyodbc-server.git
cd mcp-pyodbc-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-pyodbc-server", "run", "mcp-pyodbc-server"],
      "env": {
        "ODBC_DSN": "dsn_name",
        "ODBC_USER": "username",
        "ODBC_PASSWORD": "password",
        "API_KEY": "sk-xxx"
      }
    }
  }
}

---

使用方法

提供的工具

成功安装后，以下工具将可供MCP客户端应用程序使用。

概览

名称	描述
podbc_get_schemas	列出连接的数据库管理系统(DBMS)可访问的所有数据库模式。
podbc_get_tables	列出与选定数据库模式关联的表。
podbc_describe_table	提供与指定数据库模式关联的表的描述。这包括关于列名、数据类型、空值处理、自动递增、主键和外键的信息。
podbc_filter_table_names	基于q输入字段中的子串模式，列出与选定数据库模式关联的表。
podbc_query_database	执行SQL查询，并以JSONL格式返回结果。
podbc_execute_query	执行SQL查询，并以JSONL格式返回结果。
podbc_execute_query_md	执行SQL查询，并以Markdown表格格式返回结果。
podbc_spasql_query	执行SPASQL查询并返回结果。
podbc_virtuoso_support_ai	与Virtuoso支持助手/代理交互——这是与LLMs交互的Virtuoso特定功能。

详细描述

• podbc_get_schemas

  • 获取并返回连接数据库中所有模式名称的列表。
  • 输入参数：
    • user (字符串，可选)：数据库用户名。默认为"demo"。
    • password (字符串，可选)：数据库密码。默认为"demo"。
    • dsn (字符串，可选)：ODBC数据源名称。默认为"Local Virtuoso"。
  • 返回一个包含模式名称的JSON字符串数组。

• podbc_get_tables

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

• podbc_filter_table_names

  • 过滤并返回名称中包含特定子串的表的信息。
  • 输入参数：
    • q (字符串，必需)：要在表名中搜索的子串。
    • schema (字符串，可选)：用于筛选表的数据库模式。默认为连接默认。
    • user (字符串，可选)：数据库用户名。默认为"demo"。
    • password (字符串，可选)：数据库密码。默认为"demo"。
    • dsn (字符串，可选)：ODBC数据源名称。默认为"Local Virtuoso"。
  • 返回一个包含匹配表信息的JSON字符串。

• podbc_describe_table

  • 获取并返回特定表列的详细信息。
  • 输入参数：
    • 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_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-pyodbc-server run mcp-pyodbc-server
   

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