mcp-odbc-server

OpenLink 的 ODBC MCP 服务

本文介绍通用 ODBC 服务（称为 mcp-odbc 服务）的设置和使用，该服务用于模型上下文协议（MCP）。它旨在通过为特定 ODBC 连接器（也称为 ODBC 驱动程序）配置的数据源名称，为大模型提供对 ODBC 可访问数据源的透明访问。

服务实现

此 ODBC MCP 服务 是基于 node-odbc 构建的小型 TypeScript 层。它通过 node.js 将调用路由到主机系统的本地 ODBC 驱动程序管理器（TypeScript 使用 npx）。

运行环境设置与先决条件

以下示例主要针对 Virtuoso ODBC 连接器，但本指南也适用于其他 ODBC 连接器。我们强烈鼓励提交与其他数据库管理系统（DBMS）相关的代码贡献和使用演示，以便纳入此项目。

关键系统组件

1. 检查 node.js 版本。如果版本低于 21.1.0，请使用以下命令升级或显式安装：

   nvm install v21.1.0
   

2. 使用以下命令安装 MCP 组件：

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
   

3. 使用以下命令设置 nvm 版本：

   nvm alias default 21.1.0
   

安装

1. 运行

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

2. 切换目录

   cd mcp-odbc-server
   

3. 运行

   npm init -y
   

4. 运行

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
   

unixODBC 运行时环境检查

1. 运行以下命令检查安装配置（即关键 INI 文件的位置）：

   odbcinst -j
   

2. 运行以下命令列出可用的数据源名称（DSN）：

   odbcinst -q -s
   

环境变量

作为良好的安全实践，应使用与 mcp-ser 位于同一目录中的 .env 文件，设置 ODBC 数据源名称（ODBC_DSN）、用户（ODBC_USER）、密码（ODBC_PWD）、ODBC INI（ODBCINI），以及在希望通过 ODBC 使用 OpenLink AI Layer（OPAL）时所需的目标大模型 API 密钥（API_KEY）。

API_KEY=sk-xxx
ODBC_DSN=Local Virtuoso
ODBC_USER=dba
ODBC_PASSWORD=dba
ODBCINI=/Library/ODBC/odbc.ini 

用法

工具

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

概览

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

详细说明

• get_schemas

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

• get_tables

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

• filter_table_names

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

• describe_table

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

• query_database

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

• query_database_md

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

• query_database_jsonl

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

• spasql_query

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

• sparql_query

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

• virtuoso_support_ai

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

基本安装测试与故障排除

MCP Inspector 工具

MCP Inspector 工具标准版

1. 在 mcp-server 目录/文件夹中使用以下命令启动检查器：

   ODBCINI=/Library/ODBC/odbc.ini npx -y @modelcontextprotocol/inspector npx tsx ./src/main.ts 
   

2. 点击“Connect”按钮，然后点击“Tools”选项卡即可开始使用。

   

OpenLink MCP Inspector 工具版

这是标准版的一个分支，修复了与此 MCP 服务配合使用时出现的 JSON 处理错误。

1. 运行

   git clone [email protected]:OpenLinkSoftware/inspector.git
   cd inspector
   

2. 运行

   npm run start
   

3. 在 http://localhost:6274 的 MCP Inspector 界面中的 Arguments 输入框内提供以下值

   tsx /path/to/mcp-odbc-server/src/main.ts
   

4. 点击 Connect 按钮，与指定的 MCP 服务初始化会话

Apple Silicon（ARM64）与 MCP ODBC 服务的兼容性问题

Node x86_64 与 arm64 冲突问题

当前可能安装的是 x86_64 版 node，但 ODBC 桥接程序和 MCP 服务组件基于 arm64。

可通过执行以下步骤解决此问题：

1. 运行以下命令卸载 x86_64 版 node：

    nvm uninstall 21.1.0
   

2. 运行以下命令，确认当前 shell 处于 arm64 模式：

   arch
   

   • 如果返回 x86_64，则运行以下命令切换当前模式：

     arch arm64
     

3. 运行以下命令安装 arm64 版 node：

   nvm install 21.1.0
   

Node 到 ODBC 桥接层不兼容

在 Apple Silicon 设备上尝试使用 Model Context Protocol（MCP）ODBC 服务时，可能会遇到架构不匹配错误。这是因为 Node.js ODBC 原生模块（odbc.node）是为 ARM64 架构编译的，但加载的是基于 x86_64 的 unixODBC 运行时版本。

典型错误消息：

Error: dlopen(...odbc.node, 0x0001): tried: '...odbc.node' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e' or 'arm64'))

请按以下步骤解决此问题：

1. 验证 Node.js 是否以 ARM64 模式运行：

   node -p "process.arch"  # Should output: `arm64`
   

2. 安装 ARM64 版 unixODBC：

   # Verify Homebrew is running in ARM64 mode
   which brew  # Should point to /opt/homebrew/bin/brew
   
   # Remove existing unixODBC
   brew uninstall --force unixodbc
   
   # Install ARM64 version
   arch -arm64 brew install unixodbc
   

3. 为 ARM64 重新构建 Node.js ODBC 模块：

   # Navigate to your project
   cd /path/to/mcp-odbc-server
   
   # Remove existing module
   rm -rf node_modules/odbc
   
   # Set architecture environment variable
   export npm_config_arch=arm64
   
   # Reinstall with force build
   npm install odbc --build-from-source
   

4. 验证模块现在是否为 ARM64：

   file node_modules/odbc/lib/bindings/napi-v8/odbc.node
   # Should show "arm64" instead of "x86_64"
   

要点

• unixODBC 和 Node.js ODBC 模块都必须兼容 ARM64
• 使用环境变量（export npm_config_arch=arm64）比使用 npm config 命令更可靠
• 始终使用 file 命令或 node -p "process.arch" 验证架构
• 在 Apple Silicon 上使用 Homebrew 时，可以在命令前加上 arch -arm64，强制使用 ARM64 二进制文件

MCP 应用用法

Claude Desktop 配置

此配置文件的路径为：~{username}/Library/Application Support/Claude/claude_desktop_config.json。

{
    "mcpServers": {
        "ODBC": {
            "command": "/path/to/.nvm/versions/node/v21.1.0/bin/node",
            "args": [
                "/path/to/mcp-odbc-server/node_modules/.bin/tsx",
                "/path/to/mcp-odbc-server/src/main.ts"
            ],
            "env": {
                "ODBCINI": "/Library/ODBC/odbc.ini",
                "NODE_VERSION": "v21.1.0",
                "PATH": "~/.nvm/versions/node/v21.1.0/bin:${PATH}"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

Claude Desktop 用法

1. 启动应用。

2. 通过“设置 | 开发者”用户界面应用上述配置。

3. 确保你已建立可用的 ODBC 连接，并连接到数据源名称（DSN）。

4. 输入要求执行查询的提示词，例如：

   Execute the following query: SELECT TOP * from Demo..Customers
   

   

Cline（Visual Studio 扩展）配置

此配置文件的路径为：~{username}/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "ODBC": {
      "command": "/path/to/.nvm/versions/node/v21.1.0/bin/node",
      "args": [
        "/path/to/mcp-odbc-server/node_modules/.bin/tsx",
        "/path/to/mcp-odbc-server/src/main.ts"
      ],
      "env": {
        "ODBCINI": "/Library/ODBC/odbc.ini",
        "NODE_VERSION": "v21.1.0",
        "PATH": "/path/to/.nvm/versions/node/v21.1.0/bin:${PATH}"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cline（Visual Studio 扩展）用法

1. 使用 Shift+Command+P 打开命令面板。

2. 输入：Cline。

3. 选择：Cline View，在 VSCode 侧边栏中打开 Cline 界面。

4. 使用四方格图标打开用于安装和配置 MCP 服务的界面。

5. 应用上述 Cline 配置。

6. 返回扩展的主界面，并开始新任务，要求处理以下提示词：

   "Execute the following query: SELECT TOP 5 * from Demo..Customers"
   

   

Cursor 配置

使用设置齿轮打开配置菜单，其中包含用于注册和配置 mcp servers 的 MCP 菜单项。

Cursor 用法

1. 使用 Command+I 或 Control+I 组合键打开聊天界面。

2. 在界面左下方的下拉菜单中选择 Agent，默认选项为 Ask。

3. 输入提示词，并按以下格式指定使用 mcp-server for odbc：@odbc {rest-of-prompt}。

4. 点击“Accept”执行提示词。

   

相关内容

• MCP Inspector 使用演示视频
• Claude Desktop 基本用法演示视频
• Cline Visual Studio Code 扩展基本用法演示视频
• Cursor Editor 基本用法演示视频