简介

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

mcp-client-and-servers|648x499

服务器实现

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

操作环境设置与先决条件

虽然以下示例主要面向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 Lines（JSONL）格式返回结果。
`execute_query`	执行SQL查询并以JSON Lines（JSONL）格式返回结果。
`execute_query_md`	执行SQL查询并以Markdown表格格式返回结果。
`spasql_query`	执行SPASQL查询并返回结果。
`sparql_query`	执行SPARQL查询并返回结果。
`virtuoso_support_ai`	与Virtuoso支持助手/代理交互——这是一个Virtuoso特定的功能，用于与LLMs交互

详细描述

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支持助手功能调用的结果（例如，DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI）。

基本安装测试与故障排除

MCP检查工具

标准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
```
在MCP Inspector的UI的Arguments输入字段中提供以下值，访问http://localhost:6274：
```
tsx /path/to/mcp-odbc-server/src/main.ts
```
点击Connect按钮以初始化与指定MCP服务器的会话。

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

Node x86_64与arm64冲突问题

可能安装了x86_64版本的node，但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
```

Node到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"  # 应输出：`arm64`
```

安装ARM64版本的unixODBC：

# 验证Homebrew是否在ARM64模式下运行
which brew  # 应指向/opt/homebrew/bin/brew

# 移除现有的unixODBC
brew uninstall --force unixodbc

# 安装ARM64版本
arch -arm64 brew install unixodbc

为ARM64重建Node.js ODBC模块：

# 导航到您的项目
cd /path/to/mcp-odbc-server

# 移除现有模块
rm -rf node_modules/odbc

# 设置架构环境变量
export npm_config_arch=arm64

# 强制重新安装
npm install odbc --build-from-source

验证模块现在是否为ARM64：

file node_modules/odbc/lib/bindings/napi-v8/odbc.node
# 应显示“arm64”而不是“x86_64”

关键点

unixODBC和Node.js ODBC模块都必须与ARM64兼容
使用环境变量（export npm_config_arch=arm64）比npm配置命令更可靠
始终使用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桌面使用

启动应用程序。
通过设置 | 开发者用户界面应用上述配置。
确保您有一个有效的ODBC连接到数据源名称（DSN）。

提交一个请求执行查询的提示，例如：

执行以下查询：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视图，这将在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}。
点击“接受”执行提示。

简介