ODBC MCP

ODBC的OpenLink MCP服务器

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

服务器实现

这 ODBC的MCP服务器 是一个构建在上面的小型TypeScript层 node-odbc。它通过以下方式将调用路由到主机系统的本地ODBC驱动程序管理器 node.js （具体使用 npx 对于TypeScript）。

操作环境设置和先决条件

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

关键系统组件

1. 检查 node.js 版本。如果不是 21.1.0 或更高版本，使用以下方式明确升级或安装：

   nvm install v21.1.0

1. 使用以下工具安装MCP组件：

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

1. 设置 nvm 版本使用：

   nvm alias default 21.1.0

安装

1. 跑

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

1. 更改目录

   cd mcp-odbc-server

1. 跑

   npm init -y

1. 跑

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

unixODBC运行时环境检查

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

   odbcinst -j

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

   odbcinst -q -s

环境变量

作为良好的安全实践，您应该使用 .env 文件位于与 mcp-ser 为ODBC数据源名称设置绑定(ODBC_DSN)，用户(ODBC_USER)，密码(ODBC_PWD)，ODBC INI(ODBCINI)，并且，如果要通过ODBC使用OpenLinkAI层（OPAL），则目标大型语言模型（LLM）API密钥(API_KEY).

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

用法

工具

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

概述

详细描述

• 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 （string，必填）：在表名中搜索的子字符串。 - schema （字符串，可选）：用于筛选表的数据库架构。默认为连接默认值。 - user （字符串，可选）：数据库用户名。默认为 "demo". - password （字符串，可选）：数据库密码。默认为 "demo". - dsn （字符串，可选）：ODBC数据源名称。默认为 "Local Virtuoso". - 返回一个JSON字符串，其中包含匹配表的信息。

• describe_table

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

• query_database

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

• query_database_md

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

• query_database_jsonl

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

• spasql_query

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

• sparql_query

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

• virtuoso_support_ai

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

基本安装测试和故障排除

MCP检查工具

规范MCP检查器工具版

1. 使用以下命令从mcp服务器目录/文件夹启动检查器：

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

1. 点击“连接”按钮，然后点击“工具”选项卡开始。

OpenLink MCP检查器工具版

这是规范版本的一个分支，其中包括与此MCP服务器使用相关的JSON处理错误修复。

1. 跑

   git clone git@github.com:OpenLinkSoftware/inspector.git
   cd inspector

1. 跑

   npm run start

1. 在中提供以下值 Arguments MCP Inspectors UI的输入字段http://localhost:6274

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

1. 点击 Connect 按钮，用于初始化与指定MCP服务器的会话

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

节点x86_64与arm64冲突问题

x86_64而不是arm64版本 node 但ODBC桥和MCP服务器是基于arm64的组件。

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

1. 卸载x86_64版本的 node 通过运行：

    nvm uninstall 21.1.0

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

   arch

- 如果返回x86_64，则运行以下命令以更改活动模式：

     arch arm64

1. 安装arm64版本 node 通过运行：

   nvm install 21.1.0

节点到ODBC网桥层不兼容

尝试在Apple Silicon计算机上使用模型上下文协议（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`

1. 为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

1. 为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

1. 验证模块现在是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桌面配置

此配置文件的路径为： ~{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桌面使用情况

1. 启动应用程序。

1. 通过设置|开发人员用户界面应用配置（从上面）。

1. 确保与数据源名称（DSN）的ODBC连接正常工作。

1. 呈现请求查询执行的提示。，

   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+命令+P 打开命令面板。

1. 键入： Cline.

1. 选择： Cline View，这将打开VSCode侧栏中的Cline UI。

1. 使用四个正方形图标访问安装和配置MCP服务器的UI。

1. 应用临床配置（如上所述）。

1. 返回扩展程序的主UI并启动一个新任务，请求处理以下提示：

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

光标配置

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

光标使用

1. 使用命令+I 或控制+I 组合键打开聊天界面。

1. 选择 Agent 从UI左下角的下拉列表中，默认值为 Ask.

1. 输入提示，限定使用 mcp-server for odbc 使用模式： @odbc {rest-of-prompt}.

1. 点击“接受”以执行提示。

相关

• MCP检查器使用截屏
• 克劳德桌面使用基本屏幕截图
• Visual Studio基本代码扩展用法截屏
• 基本光标编辑器用法屏幕投射