Java based Model Context Procotol (MCP) Server for JDBC

---

用于 JDBC 的 OpenLink MCP 服务

一个基于 Java、使用 Quakrus 构建的轻量级 JDBC MCP（Model Context Protocol）服务。 此服务兼容 Virtuoso DBMS 以及任何其他具有 JDBC 驱动程序的 DBMS 后端。

---

功能

• 获取架构：从已连接的数据库中获取并列出所有架构名称。
• 获取表：检索指定架构或所有架构的表信息。
• 描述表：生成表结构的详细描述，包括：
  • 列名称和数据类型
  • 可空属性
  • 主键和外键
• 搜索表：根据名称子字符串筛选并检索表。
• 执行存储过程：Virtuoso 专属功能！ 执行存储过程并检索结果。
• 执行查询：
  • JSONL 结果格式：针对结构化响应进行了优化。
  • Markdown 表格格式：适用于报告和可视化。

---

前置条件

MCP 服务需要 Java 21 或更高版本。

---

安装

克隆此仓库：

git clone https://github.com/OpenLinkSoftware/mcp-jdbc-server.git  
cd mcp-jdbc-server

环境变量

通过覆盖以下默认值来更新 .env，以符合您的偏好：

jdbc.url=jdbc:virtuoso://localhost:1111
jdbc.user=dba
jdbc.password=dba
jdbc.api_key=xxx

---

配置

使用 Virtuoso 及其 JDBC 驱动程序的 Claude Desktop 用户：

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "my_database": {
      "command": "java",
      "args": ["-jar", "/path/to/mcp-jdbc-server/MCPServer-1.0.0-runner.jar"],
      "env": {
        "jdbc.url": "jdbc:virtuoso://localhost:1111",
        "jdbc.user": "username",
        "jdbc.password": "password",
        "jdbc.api_key": "sk-xxx"
      }
    }
  }
}

使用其他 JDBC 驱动程序或组合使用多个驱动程序的 Claude Desktop 用户：

将以下内容编辑为适合本地环境的配置，然后添加到 claude_desktop_config.json：

    "jdbc": {
      "command": "java",
      "args": [
        "-cp",
        "/path/to/mcp-jdbc-server/MCPServer-1.0.0-runner.jar:/path/to/jdbc_driver1.jar:/path/to/jdbc_driverN.jar",
        "io.quarkus.runner.GeneratedMain"
      ],
      "env": {
        "jdbc.url": "jdbc:virtuoso://localhost:1111",
        "jdbc.user": "dba",
        "jdbc.password": "dba"
      }
    }

---

使用

提供的工具

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

概览

name	description
jdbc_get_schemas	列出已连接的数据库管理系统（DBMS）可访问的数据库架构。
jdbc_get_tables	列出与所选数据库架构关联的表。
jdbc_describe_table	提供与指定数据库架构关联的表的描述，包括列名称、数据类型、空值处理、自增、主键和外键信息。
jdbc_filter_table_names	根据 q 输入字段中的子字符串模式，列出与所选数据库架构关联的表。
jdbc_query_database	执行 SQL 查询并以 JSONL 格式返回结果。
jdbc_execute_query	执行 SQL 查询并以 JSONL 格式返回结果。
jdbc_execute_query_md	执行 SQL 查询并以 Markdown 表格格式返回结果。
jdbc_spasql_query	Virtuoso 专属功能！ 执行 SPASQL 查询并返回结果。
jdbc_sparql_query	Virtuoso 专属功能！ 执行 SPARQL 查询并返回结果。
jdbc_virtuoso_support_ai	Virtuoso 专属功能！ 通过 Virtuoso Support Assistant/Agent 与大模型交互。

详细说明

• jdbc_get_schemas

  • 从已连接的数据库中检索并返回所有架构名称的列表。
  • 输入参数：
    • user（字符串，可选）：数据库用户名。默认为 "demo"。
    • password（字符串，可选）：数据库密码。默认为 "demo"。
    • url（字符串，可选）：JDBC URL 连接字符串。
  • 返回架构名称的 JSON 字符串数组。

• jdbc_get_tables

  • 检索并返回指定架构中的表信息列表。如果未提供架构，则使用连接的默认架构。
  • 输入参数：
    • schema（string，可选）：用于筛选表的数据库架构。默认为连接的默认架构。
    • user（string，可选）：数据库用户名。默认为 "demo"。
    • password（string，可选）：数据库密码。默认为 "demo"。
    • url（string，可选）：JDBC URL 连接字符串。
  • 返回包含表信息的 JSON 字符串（例如，TABLE_CAT、TABLE_SCHEM、TABLE_NAME、TABLE_TYPE）。

• jdbc_filter_table_names

  • 筛选并返回名称包含指定子字符串的表的信息。
  • 输入参数：
    • q（string，必需）：要在表名中搜索的子字符串。
    • schema（string，可选）：用于筛选表的数据库架构。默认为连接的默认架构。
    • user（string，可选）：数据库用户名。默认为 "demo"。
    • password（string，可选）：数据库密码。默认为 "demo"。
    • url（string，可选）：JDBC URL 连接字符串。
  • 返回包含匹配表信息的 JSON 字符串。

• jdbc_describe_table

  • 检索并返回指定表的列的详细信息。
  • 输入参数：
    • schema（string，必需）：包含该表的数据库架构名称。
    • table（string，必需）：要描述的表名。
    • user（string，可选）：数据库用户名。默认为 "demo"。
    • password（string，可选）：数据库密码。默认为 "demo"。
    • url（string，可选）：JDBC URL 连接字符串。
  • 返回描述表列的 JSON 字符串（例如，COLUMN_NAME、TYPE_NAME、COLUMN_SIZE、IS_NULLABLE）。

• jdbc_query_database

  • 执行标准 SQL 查询，并以 JSON 格式返回结果。
  • 输入参数：
    • query（string，必需）：要执行的 SQL 查询字符串。
    • user（string，可选）：数据库用户名。默认为 "demo"。
    • password（string，可选）：数据库密码。默认为 "demo"。
    • url（string，可选）：JDBC URL 连接字符串。
  • 以 JSON 字符串形式返回查询结果。

• jdbc_query_database_md

  • 执行标准 SQL 查询，并将结果格式化为 Markdown 表格。
  • 输入参数：
    • query（string，必需）：要执行的 SQL 查询字符串。
    • user（string，可选）：数据库用户名。默认为 "demo"。
    • password（string，可选）：数据库密码。默认为 "demo"。
    • url（string，可选）：JDBC URL 连接字符串。
  • 以 Markdown 表格字符串形式返回查询结果。

• jdbc_query_database_jsonl

  • 执行标准 SQL 查询，并以 JSON Lines（JSONL）格式返回结果（每行一个 JSON 对象）。
  • 输入参数：
    • query（string，必需）：要执行的 SQL 查询字符串。
    • user（string，可选）：数据库用户名。默认为 "demo"。
    • password（string，可选）：数据库密码。默认为 "demo"。
    • url（string，可选）：JDBC URL 连接字符串。
  • 以 JSONL 字符串形式返回查询结果。

• jdbc_spasql_query

  • Virtuoso 专属功能！
  • 执行 SPASQL（SQL/SPARQL 混合）查询并返回结果。
  • 输入参数：
    • query（string，必需）：SPASQL 查询字符串。
    • max_rows（number，可选）：要返回的最大行数。默认为 20。
    • timeout（number，可选）：查询超时时间，单位为毫秒。默认为 30000（即 30 秒）。
    • user（string，可选）：数据库用户名。默认为 "demo"。
    • password（string，可选）：数据库密码。默认为 "demo"。
    • url（string，可选）：JDBC URL 连接字符串。
  • 返回底层存储过程调用的结果（例如，Demo.demo.execute_spasql_query）。

• jdbc_sparql_query

  • Virtuoso 专属功能！
  • 执行 SPARQL 查询并返回结果。
  • 输入参数：
    • query（字符串，必填）：SPARQL 查询字符串。
    • format（字符串，可选）：所需的结果格式。默认为 'json'。
    • timeout（数字，可选）：查询超时时间，单位为毫秒。默认为 30000（即 30 秒）。
    • user（字符串，可选）：数据库用户名。默认为 "demo"。
    • password（字符串，可选）：数据库密码。默认为 "demo"。
    • url（字符串，可选）：JDBC URL 连接字符串。
  • 返回底层函数调用的结果（例如，"UB".dba."sparqlQuery"）。

• jdbc_virtuoso_support_ai

  • Virtuoso 专属功能！
  • 调用 Virtuoso 专属的 AI 助手函数，并传入提示词和可选的 API 密钥。
  • 输入参数：
    • prompt（字符串，必填）：AI 函数的提示词文本。
    • api_key（字符串，可选）：AI 服务的 API 密钥。默认为 "none"。
    • user（字符串，可选）：数据库用户名。默认为 "demo"。
    • password（字符串，可选）：数据库密码。默认为 "demo"。
    • url（字符串，可选）：JDBC URL 连接字符串。
  • 返回 AI 支持助手函数调用的结果（例如，DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI）。

---

基本用法与故障排查

使用 MCP Inspector 连接 Virtuoso 的 ODBC 驱动程序

如需了解 MCP 客户端的基本用法和故障排查，请按以下步骤使用 MCP Inspector：

1. 安装 MCP Inspector：

   npm install -g @modelcontextprotocol/inspector
   

2. 启动 Inspector：

   npx @modelcontextprotocol/inspector java -jar /path/to/mcp-jdbc-server/MCPServer-1.0.0-runner.jar
   

访问 Inspector 返回的 URL，以排查 MCP 服务交互问题。

使用 MCP Inspector 连接其他驱动程序

如需了解 MCP 客户端的基本用法和故障排查，请按以下步骤使用 MCP Inspector：

1. 安装 JDBC 驱动程序，确保其 JAR 文件通过 $CLASSPATH 注册到主机操作系统的 Java 虚拟机（JVM）中。例如：

   export CLASSPATH=$CLASSPATH:/path/to/driver1.jar:/path/to/driver2.jar:/path/to/driverN.jar
   

2. 使用以下命令行参数启动 Inspector：

   npx @modelcontextprotocol/inspector java -cp MCPServer-1.0.0-runner.jar:/path/to/driver1.jar:/path/to/driver2.jar:/path/to/driverN.jar io.quarkus.runner.GeneratedMain
   

基于 Oracle 和 Informix 驱动程序的使用示例

0. 假设 JDBC 驱动程序信息如下：

   • Oracle JDBC 驱动程序 URL 模板

     jdbc:oracle:thin:@<hostname>:[port]:<SERVICEID>
     

   • Informix JDBC 驱动程序 URL 模板

     jdbc:informix-sqli://<hostname>:<port>/<database></database>:<INFORMIXSERVER>=<SERVICEID>
     

1. 安装 Oracle（ojdbc17.jar）和/或 Informix（jdbc-15.0.0.1.1.jar）JDBC 驱动程序，并确保其 JAR 文件通过 $CLASSPATH 注册到主机操作系统的 Java 虚拟机（JVM）中。例如：

    export CLASSPATH=$CLASSPATH:/path/to/Java/Extensions/jdbc-15.0.0.1.1.jar
    export CLASSPATH=$CLASSPATH:/path/to/Java/Extensions/ojdbc17.jar
   

2. 使用以下命令行参数启动 Inspector：

   npx @modelcontextprotocol/inspector java -cp MCPServer-1.0.0-runner.jar:/path/to/Java/Extensions/ojdbc17.jar:/path/to/Java/Extensions/jdbc-15.0.0.1.1.jar io.quarkus.runner.GeneratedMain
   

3. 访问 Inspector 返回的 URL，然后使用 jdbc_execute_query 操作查询目标数据库，并为以下输入字段模板提供实际值：

   • JDBC URL
   • 用户名
   • 密码
   • 查询