MCP JDBC Server

---

Servidor MCP OpenLink para JDBC

Un servidor MCP (Protocolo de Contexto de Modelo) ligero basado en Java para JDBC, construido con Quakrus. Este servidor es compatible con Virtuoso DBMS y cualquier otro backend de DBMS que tenga un controlador JDBC.

---

Características

• Obtener Esquemas: Recupera y lista todos los nombres de esquemas de la base de datos conectada.
• Obtener Tablas: Recupera información de tablas para esquemas específicos o todos los esquemas.
• Describir Tabla: Genera una descripción detallada de las estructuras de las tablas, incluyendo:
  • Nombres de columnas y tipos de datos
  • Atributos anulables
  • Claves primarias y foráneas
• Buscar Tablas: Filtra y recupera tablas basándose en subcadenas del nombre.
• Ejecutar Procedimientos Almacenados: ¡Una característica específica de Virtuoso! Ejecuta procedimientos almacenados y recupera resultados.
• Ejecutar Consultas:
  • Formato de resultado JSONL: Optimizado para respuestas estructuradas.
  • Formato de tabla Markdown: Ideal para informes y visualización.

---

Requisitos Previos

El servidor MCP requiere Java 21 o superior.

---

Instalación

Clona este repositorio:

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

Variables de Entorno

Actualiza tu .env sobrescribiendo estos valores predeterminados para que coincidan con tus preferencias:

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

---

Configuración

Para usuarios de Claude Desktop que usan Virtuoso y su controlador JDBC:

Agrega lo siguiente a 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"
      }
    }
  }
}

Para usuarios de Claude Desktop que usan otro controlador JDBC o una combinación de controladores:

Agrega lo siguiente, editado para adaptarse a tu entorno local, a 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"
      }
    }

---

Uso

Herramientas Proporcionadas

Después de una instalación exitosa, las siguientes herramientas estarán disponibles para las aplicaciones cliente MCP.

Resumen

nombre	descripción
jdbc_get_schemas	Lista los esquemas de base de datos accesibles para el sistema de gestión de base de datos (DBMS) conectado.
jdbc_get_tables	Lista las tablas asociadas con un esquema de base de datos seleccionado.
jdbc_describe_table	Proporciona la descripción de una tabla asociada con un esquema de base de datos designado. Esto incluye información sobre nombres de columnas, tipos de datos, manejo de nulos, autoincremento, clave primaria y claves foráneas.
jdbc_filter_table_names	Lista tablas, basándose en un patrón de subcadena del campo de entrada q, asociadas con un esquema de base de datos seleccionado.
jdbc_query_database	Ejecuta una consulta SQL y devuelve resultados en formato JSONL.
jdbc_execute_query	Ejecuta una consulta SQL y devuelve resultados en formato JSONL.
jdbc_execute_query_md	Ejecuta una consulta SQL y devuelve resultados en formato de tabla Markdown.
jdbc_spasql_query	¡Una característica específica de Virtuoso! Ejecuta una consulta SPASQL y devuelve resultados.
jdbc_sparql_query	¡Una característica específica de Virtuoso! Ejecuta una consulta SPARQL y devuelve resultados.
jdbc_virtuoso_support_ai	¡Una característica específica de Virtuoso! Interactúa con LLMs a través del Asistente/Agente de Soporte de Virtuoso.

Descripción Detallada

• jdbc_get_schemas

  • Recupera y devuelve una lista de todos los nombres de esquemas de la base de datos conectada.
  • Parámetros de entrada:
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve una matriz JSON de cadenas con los nombres de los esquemas.

• jdbc_get_tables

  • Recupera y devuelve una lista que contiene información sobre tablas en un esquema especificado. Si no se proporciona ningún esquema, usa el esquema predeterminado de la conexión.
  • Parámetros de entrada:
    • schema (cadena, opcional): Esquema de base de datos para filtrar tablas. Predeterminado a la conexión predeterminada.
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve una cadena JSON que contiene información de tablas (por ejemplo, TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TABLE_TYPE).

• jdbc_filter_table_names

  • Filtra y devuelve información sobre tablas cuyos nombres contienen una subcadena específica.
  • Parámetros de entrada:
    • q (cadena, requerido): La subcadena a buscar dentro de los nombres de las tablas.
    • schema (cadena, opcional): Esquema de base de datos para filtrar tablas. Predeterminado a la conexión predeterminada.
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve una cadena JSON que contiene información para las tablas coincidentes.

• jdbc_describe_table

  • Recupera y devuelve información detallada sobre las columnas de una tabla específica.
  • Parámetros de entrada:
    • schema (cadena, requerido): El nombre del esquema de base de datos que contiene la tabla.
    • table (cadena, requerido): El nombre de la tabla a describir.
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve una cadena JSON que describe las columnas de la tabla (por ejemplo, COLUMN_NAME, TYPE_NAME, COLUMN_SIZE, IS_NULLABLE).

• jdbc_query_database

  • Ejecuta una consulta SQL estándar y devuelve los resultados en formato JSON.
  • Parámetros de entrada:
    • query (cadena, requerido): La cadena de consulta SQL a ejecutar.
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve los resultados de la consulta como una cadena JSON.

• jdbc_query_database_md

  • Ejecuta una consulta SQL estándar y devuelve los resultados formateados como una tabla Markdown.
  • Parámetros de entrada:
    • query (cadena, requerido): La cadena de consulta SQL a ejecutar.
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve los resultados de la consulta como una cadena de tabla Markdown.

• jdbc_query_database_jsonl

  • Ejecuta una consulta SQL estándar y devuelve los resultados en formato JSON Lines (JSONL) (un objeto JSON por línea).
  • Parámetros de entrada:
    • query (cadena, requerido): La cadena de consulta SQL a ejecutar.
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve los resultados de la consulta como una cadena JSONL.

• jdbc_spasql_query

  • ¡Una característica específica de Virtuoso!
  • Ejecuta una consulta SPASQL (híbrido SQL/SPARQL) y devuelve resultados.
  • Parámetros de entrada:
    • query (cadena, requerido): La cadena de consulta SPASQL.
    • max_rows (número, opcional): Número máximo de filas a devolver. Predeterminado a 20.
    • timeout (número, opcional): Tiempo de espera de la consulta en milisegundos. Predeterminado a 30000 (es decir, 30 segundos).
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve el resultado de la llamada al procedimiento almacenado subyacente (por ejemplo, Demo.demo.execute_spasql_query).

• jdbc_sparql_query

  • ¡Una característica específica de Virtuoso!
  • Ejecuta una consulta SPARQL y devuelve resultados.
  • Parámetros de entrada:
    • query (cadena, requerido): La cadena de consulta SPARQL.
    • format (cadena, opcional): Formato de resultado deseado. Predeterminado a 'json'.
    • timeout (número, opcional): Tiempo de espera de la consulta en milisegundos. Predeterminado a 30000 (es decir, 30 segundos).
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve el resultado de la llamada a la función subyacente (por ejemplo, "UB".dba."sparqlQuery").

• jdbc_virtuoso_support_ai

  • ¡Una característica específica de Virtuoso!
  • Utiliza una función de Asistente de IA específica de Virtuoso, pasando un prompt y una clave API opcional.
  • Parámetros de entrada:
    • prompt (cadena, requerido): El texto del prompt para la función de IA.
    • api_key (cadena, opcional): Clave API para el servicio de IA. Predeterminado a "none".
    • user (cadena, opcional): Nombre de usuario de la base de datos. Predeterminado a "demo".
    • password (cadena, opcional): Contraseña de la base de datos. Predeterminado a "demo".
    • url (cadena, opcional): Cadena de conexión URL JDBC.
  • Devuelve el resultado de la llamada a la función del Asistente de Soporte de IA (por ejemplo, DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI).

---

Uso Básico y Solución de Problemas

Inspector MCP Conectándose al Controlador ODBC de Virtuoso

Para el uso básico del cliente MCP y la solución de problemas, usa el Inspector MCP de la siguiente manera:

1. Instala el Inspector MCP:

   npm install -g @modelcontextprotocol/inspector
   

2. Inicia el inspector:

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

Accede a la URL devuelta por el inspector para solucionar problemas de interacciones con el servidor MCP.

Inspector MCP Conectándose a Controladores Adicionales

Para el uso básico del cliente MCP y la solución de problemas, usa el Inspector MCP de la siguiente manera:

1. Instala los controladores JDBC, asegurándote de que sus archivos JAR estén registrados con la Máquina Virtual de Java (JVM) del sistema operativo anfitrión a través de $CLASSPATH. Por ejemplo:

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

2. Inicia el inspector usando los siguientes argumentos de línea de comandos:

   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
   

Ejemplo de Uso Basado en Controladores Oracle e Informix

0. Suponiendo la siguiente información del controlador JDBC:

   • Plantilla de URL del Controlador JDBC de Oracle

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

   • Plantilla de URL del Controlador JDBC de Informix

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

1. Instala los controladores JDBC de Oracle (ojdbc17.jar) y/o Informix (jdbc-15.0.0.1.1.jar), y asegúrate de que sus archivos JAR estén registrados con la Máquina Virtual de Java (JVM) del sistema operativo anfitrión a través de $CLASSPATH. Por ejemplo:

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

2. Inicia el inspector usando los siguientes argumentos de línea de comandos:

   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. Accede a la URL devuelta por el inspector y luego usa la operación jdbc_execute_query para consultar la base de datos objetivo, proporcionando valores reales para las siguientes plantillas de campos de entrada:

   • URL JDBC
   • Usuario
   • Contraseña
   • Consulta