简介

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

服务器实现

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

运行环境设置和先决条件

虽然以下示例面向 Virtuoso ODBC 连接器，但本指南也适用于其他 ODBC 连接器。我们强烈鼓励代码贡献和与此项目中包含的其他数据库管理系统相关的用法演示提交。

关键系统组件

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. 将条目 "type":"module" 添加到 package.json 文件
5. 运行 npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

unixODBC 运行时环境检查

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

环境变量

作为良好的安全实践，您应该使用与 mcp-ser 位于同一目录中的 .env 文件来设置目标大型语言模型 API 密钥（如果您想通过 ODBC 使用 OpenLink AI Layer (OPAL)）、ODBC 数据源名称 (ODBC_DSN)、用户 (ODBC_USER)、密码 (ODBC_PWD) 和 ODBC INI (ODBCINI) 的绑定。

API_KEY=sk-xxx
ODBC_DSN=Local Virtuoso
ODBC_USER=dba
ODBC_PASSWORD=dba
ODBCINI=/Library/ODBC/odbc.ini 

用法

工具

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

概述

name	description
get_schemas	列出连接的数据库管理系统 (DBMS) 可访问的数据库模式。
get_tables	列出与选定数据库模式关联的表。
describe_table	提供与指定数据库模式关联的表的描述。这包括有关列名、数据类型、空值处理、自动递增、主键和外键的信息
filter_table_names	根据来自 q 输入字段的子字符串模式，列出与选定数据库模式关联的表。
query_database	执行 SQL 查询并以 JSONL 格式返回结果。
execute_query	执行 SQL 查询并以 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"。
  • 返回包含表信息的 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。
    • user（字符串，可选）：数据库用户名。默认为 "demo"。
    • password（字符串，可选）：数据库密码。默认为 "demo"。
    • dsn（字符串，可选）：ODBC 数据源名称。默认为 "Local Virtuoso"。
  • 返回来自底层存储过程调用的结果（例如，Demo.demo.execute_spasql_query）。

• sparql_query

  • 执行 SPARQL 查询并返回结果。这是一个 Virtuoso 特定的功能。
  • 输入参数：
    • query（字符串，必需）：SPARQL 查询字符串。
    • format（字符串，可选）：所需的结果格式。默认为 'json'。
    • timeout（数字，可选）：查询超时时间（毫秒）。默认为 30000。
    • 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）。

基本安装测试和故障排除

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

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

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

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/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 用法

1. 启动应用程序
2. 通过“设置 | 开发者用户界面”应用配置（如上所示）
3. 确保您具有与数据源名称 (DSN) 的有效 ODBC 连接
4. 呈现请求查询执行的提示，例如，Execute the following query: SELECT TOP * from Demo..Customers

Cline (Visual Studio Extension) 配置

此配置文件的路径为：~{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 Extension) 用法

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”

Cursor 配置

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

Cursor 用法

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

相关

• MCP Inspector 用法截屏视频
• 基本 Claude Desktop 用法截屏视频
• 基本 Cline Visual Studio Code 扩展用法截屏视频
• 基本 Cursor Editor 用法截屏视频