mcp-odbc

介绍

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

服务器实现

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

操作环境设置和先决条件

虽然以下示例主要针对 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 层 (OPAL)，则还应设置目标大型语言模型 (LLM) API 密钥 ( API_KEY )。

用法

工具

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

概述

详细描述

• 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 检查器工具版

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

OpenLink MCP 检查器工具版

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

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

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

Node x86_64 与 arm64 冲突问题

node可能采用 x86_64 版本而不是 arm64 版本，但 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

节点与 ODBC 桥层不兼容

在 Apple Silicon 设备上尝试使用模型上下文协议 (MCP) ODBC 服务器时，您可能会遇到架构不匹配错误。出现这种情况的原因是，Node.js ODBC 原生模块 ( odbc.node ) 是针对 ARM64 架构编译的，但加载的是基于 x86_64 版本的 unixODBC 运行时。

典型错误信息：

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

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桌面配置

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

Claude 桌面使用情况

1. 启动应用程序。
2. 通过“设置”|“开发人员用户界面”应用配置（从上面）。
3. 确保您与数据源名称 (DSN) 具有有效的 ODBC 连接。
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

Cline（Visual Studio 扩展）用法

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

游标配置

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

游标使用

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

有关的

• MCP 检查器使用截屏视频
• Claude 桌面基本使用截屏视频
• 基本 Cline Visual Studio Code 扩展使用截屏视频
• 基本光标编辑器使用截屏视频