AI导哈

ODBC数据访问服务器

OpenLink MCP Server for ODBC 是一个基于TypeScript的ODBC服务器，为大型语言模型提供透明访问ODBC数据源的能力，支持多种数据库查询操作。

  • by OpenLinkSoftware
  • TypeScript
  • 本地部署
  • 13 星标
  • 更新于
在 GitHub 查看 OpenLinkSoftware/mcp-odbc-server

使用说明

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
  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

环境变量

作为良好的安全实践，您应该使用 .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 列出连接的数据库管理系统（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 与维塔索支持助手/代理交互——维塔索与LLM交互的特定功能

详细描述

  • 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

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

OpenLink MCP检查器工具版

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

  1. 跑
    git clone git@github.com:OpenLinkSoftware/inspector.git
cd inspector
  2. 跑
    npm run start
  3. 在中提供以下值 Arguments MCP Inspectors UI的输入字段http://localhost:6274
    tsx /path/to/mcp-odbc-server/src/main.ts
  4. 点击 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
  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运行时版本。

典型错误消息：

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`

  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.

{
    "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. 启动应用程序。

  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

{
  "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 打开命令面板。

  2. 键入： Cline.

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

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

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

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

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

光标配置

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

光标使用

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

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

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

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

相关

相关 MCP