mcp-odbc服务器

Name: mcp-odbc服务器
Author: OpenLinkSoftware

作者：OpenLinkSoftware9 星标更新：2025-07-24

安装使用来源：spider==github.com

项目介绍

OpenLink MCP Server for ODBC

本文档涵盖了为模型上下文协议（MCP）设置和使用的通用ODBC服务器，称为mcp-odbc服务器。它旨在通过特定ODBC连接器（也称为ODBC驱动程序）配置的数据源名称（DSN），为大型语言模型提供透明访问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支持助手/代理交互——这是一个用于与LLMs交互的Virtuoso特定功能。

详细描述

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 Inspector工具

正规MCP Inspector工具版

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

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

单击“连接”按钮，然后单击“工具”选项卡开始操作。

OpenLink MCP Inspector工具版

这是正规版的一个分支，包含了与本MCP服务器一起使用时相关的JSON处理bug修复。

运行

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

运行
```
npm run start
```
在http://localhost:6274的MCP Inspectors UI的“参数”输入字段中提供以下值：
```
tsx /path/to/mcp-odbc-server/src/main.ts
```
单击“连接”按钮以初始化与指定MCP服务器的会话。

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

Node x86_64与arm64冲突问题

可能是x86_64而不是arm64版本的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): 尝试过：'...odbc.node'（mach-o文件，但架构不兼容（有'x86_64'，需要'arm64e'或'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

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

# 导航到您的项目
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 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使用

启动应用程序。
通过设置 | 开发者用户界面应用上述配置。
确保您有一个有效的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