介绍

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

mcp-客户端和服务器|648x499

服务器实现

此**MCP 服务器用于 ODBC，**是一个构建于node-odbc之上的小型 TypeScript 层。它通过node.js （具体来说，使用npx实现 TypeScript）将调用路由到主机系统的本地 ODBC 驱动程序管理器。

Related MCP server: ODBC MCP Server

操作环境设置和先决条件

虽然以下示例主要针对 Virtuoso ODBC 连接器，但本指南也适用于其他 ODBC 连接器。我们强烈建议您贡献代码并提交与其他数据库管理系统 (DBMS) 相关的使用演示，以将其纳入本项目。

关键系统组件

检查node.js版本。如果版本低于21.1.0或更高，请使用以下命令进行升级或安装：
nvm install v21.1.0
使用以下方式安装 MCP 组件：
npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
使用以下命令设置nvm版本：
nvm alias default 21.1.0

安装

跑步
git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git
更改目录
cd mcp-odbc-server
跑步
npm init -y
跑步
npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

unixODBC 运行时环境检查

通过运行以下命令检查安装配置（即关键 INI 文件的位置）：
odbcinst -j
通过运行以下命令列出可用的数据源名称（DSN）：
odbcinst -q -s

环境变量

作为良好的安全做法，您应该使用与mcp-ser位于同一目录中的.env文件来设置 ODBC 数据源名称 ( ODBC_DSN )、用户 ( ODBC_USER )、密码 ( ODBC_PWD )、ODBC INI ( ODBCINI ) 的绑定，如果您想通过 ODBC 使用 OpenLink AI 层 (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`	列出连接的数据库管理系统 (DBMS) 可访问的数据库模式。
`get_tables`	列出与选定数据库模式关联的表。
`describe_table`	提供与指定数据库模式关联的表的描述。这包括有关列名、数据类型、空值处理、自动增量、主键和外键的信息。
`filter_table_names`	根据 `q` 输入字段中的子字符串模式，列出与所选数据库模式关联的表。
`query_database`	执行 SQL 查询并以 JSON 行 (JSONL) 格式返回结果。
`execute_query`	执行 SQL 查询并以 JSON 行 (JSONL) 格式返回结果。
`execute_query_md`	执行 SQL 查询并以 Markdown 表格式返回结果。
`spasql_query`	执行SPASQL查询并返回结果。
`sparql_query`	执行 SPARQL 查询并返回结果。
`virtuoso_support_ai`	与 Virtuoso 支持助手/代理进行交互——Virtuoso 特有的与 LLM 交互的功能

详细描述

get_schemas
- 从连接的数据库中检索并返回所有模式名称的列表。
- 输入参数：
  - user （字符串，可选）：数据库用户名。默认为"demo" 。
  - password （字符串，可选）：数据库密码。默认为"demo" 。
  - dsn （字符串，可选）：ODBC 数据源名称。默认为"Local Virtuoso" 。
- 返回模式名称的 JSON 字符串数组。
get_tables
- 检索并返回包含指定架构中表的信息的列表。如果未提供架构，则使用连接的默认架构。
- 输入参数：
  - schema （字符串，可选）：用于过滤表的数据库模式。默认为连接默认值。
  - user （字符串，可选）：数据库用户名。默认为"demo" 。
  - password （字符串，可选）：数据库密码。默认为"demo" 。
  - dsn （字符串，可选）：ODBC 数据源名称。默认为"Local Virtuoso" 。
- 返回包含表信息（例如TABLE_CAT 、 TABLE_SCHEM 、 TABLE_NAME 、 TABLE_TYPE ）的 JSON 字符串。
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 行 (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 （number，可选）：查询超时时间，以毫秒为单位。默认为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 支持助手函数调用的结果（例如， DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI ）。

基本安装测试和故障排除

MCP 检查工具

Canonical MCP 检查器工具版

使用以下命令从 mcp-server 目录/文件夹启动检查器：
ODBCINI=/Library/ODBC/odbc.ini npx -y @modelcontextprotocol/inspector npx tsx ./src/main.ts
单击“连接”按钮，然后单击“工具”选项卡即可开始。

OpenLink MCP 检查器工具版

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

跑步
git clone git@github.com:OpenLinkSoftware/inspector.git cd inspector
跑步
npm run start
在http://localhost:6274 的MCP Inspectors UI 的Arguments输入字段中提供以下值
tsx /path/to/mcp-odbc-server/src/main.ts
单击Connect按钮，初始化与指定 MCP 服务器的会话

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

Node x86_64 与 arm64 冲突问题

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

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

通过运行以下命令卸载 x86_64 版本的node ：
nvm uninstall 21.1.0
运行以下命令确认当前 shell 处于 arm64 模式：
arch
- 如果返回 x86_64，则运行以下命令来更改活动模式：
  arch arm64
通过运行以下命令安装 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'))

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

验证您的 Node.js 是否在 ARM64 模式下运行：
node -p "process.arch" # Should output: `arm64`
为 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
为 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
验证模块现在是 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 桌面使用情况

启动应用程序。
通过“设置”|“开发人员用户界面”应用配置（从上面）。
确保您与数据源名称 (DSN) 具有有效的 ODBC 连接。
显示请求查询执行的提示，例如，
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 扩展）用法

使用 Shift+Command+P 打开命令面板。
输入： Cline 。
选择：Cline View，将在 VSCode 侧边栏中打开 Cline UI。
使用四方块图标访问安装和配置 MCP 服务器的 UI。
应用 Cline 配置（从上面）。
返回扩展程序的主 UI 并启动新任务请求处理以下提示：
"Execute the following query: SELECT TOP 5 * from Demo..Customers"

游标配置

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

游标使用

使用Command + I或Control + I组合键打开聊天界面。
从 UI 左下方的下拉菜单中选择Agent ，默认值为Ask 。
输入您的提示，使用以下模式限定mcp-server for odbc使用： @odbc {rest-of-prompt} 。
单击“接受”以执行提示。

mcp-odbc

介绍