MCP JDBC Server

Um servidor MCP leve para qualquer banco de dados com driver JDBC. Construído com Quarkus e requer Java 21+.

GitHub
13

Documentação

Servidor MCP OpenLink para JDBC

Um servidor MCP (Model Context Protocol) leve baseado em Java para JDBC, construído com Quarkus. Este servidor é compatível com o Virtuoso DBMS e qualquer outro backend de banco de dados que possua um driver JDBC.

mcp-client-and-servers|648x499

Recursos

  • Obter Schemas: Busca e lista todos os nomes de schemas do banco de dados conectado.
  • Obter Tabelas: Recupera informações de tabelas para schemas específicos ou todos os schemas.
  • Descrever Tabela: Gera uma descrição detalhada das estruturas das tabelas, incluindo:
    • Nomes das colunas e tipos de dados
    • Atributos de nulidade
    • Chaves primárias e estrangeiras
  • Pesquisar Tabelas: Filtra e recupera tabelas com base em substrings do nome.
  • Executar Procedimentos Armazenados: Um recurso específico do Virtuoso! Executa procedimentos armazenados e recupera resultados.
  • Executar Consultas:
    • Formato de resultado JSONL: Otimizado para respostas estruturadas.
    • Formato de tabela Markdown: Ideal para relatórios e visualização.

Pré-requisitos

O servidor MCP requer Java 21 ou superior.

Instalação

Clone este repositório:

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

Variáveis de Ambiente

Atualize seu .env substituindo estes padrões para corresponder às suas preferências:

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

Configuração

Para usuários do Claude Desktop que utilizam Virtuoso e seu driver JDBC:

Adicione o seguinte ao 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 usuários do Claude Desktop que utilizam outro driver JDBC ou uma combinação de drivers:

Adicione o seguinte, editado para adequar-se ao seu ambiente local, ao 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

Ferramentas Fornecidas

Após a instalação bem-sucedida, as seguintes ferramentas estarão disponíveis para aplicativos clientes MCP.

Visão Geral

nomedescrição
jdbc_get_schemasLista os schemas do banco de dados acessíveis ao sistema de gerenciamento de banco de dados (DBMS) conectado.
jdbc_get_tablesLista as tabelas associadas a um schema de banco de dados selecionado.
jdbc_describe_tableFornece a descrição de uma tabela associada a um schema de banco de dados designado. Isso inclui informações sobre nomes de colunas, tipos de dados, tratamento de nulos, autoincremento, chave primária e chaves estrangeiras.
jdbc_filter_table_namesLista tabelas, com base em um padrão de substring do campo de entrada q, associadas a um schema de banco de dados selecionado.
jdbc_query_databaseExecuta uma consulta SQL e retorna os resultados no formato JSONL.
jdbc_execute_queryExecuta uma consulta SQL e retorna os resultados no formato JSONL.
jdbc_execute_query_mdExecuta uma consulta SQL e retorna os resultados no formato de tabela Markdown.
jdbc_spasql_queryUm recurso específico do Virtuoso! Executa uma consulta SPASQL e retorna os resultados.
jdbc_sparql_queryUm recurso específico do Virtuoso! Executa uma consulta SPARQL e retorna os resultados.
jdbc_virtuoso_support_aiUm recurso específico do Virtuoso! Interage com LLMs por meio do Assistente/Agente de Suporte do Virtuoso.

Descrição Detalhada

  • jdbc_get_schemas

    • Recupera e retorna uma lista de todos os nomes de schemas do banco de dados conectado.
    • Parâmetros de entrada:
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna um array de strings JSON com os nomes dos schemas.

  • jdbc_get_tables

    • Recupera e retorna uma lista contendo informações sobre tabelas em um schema especificado. Se nenhum schema for fornecido, usa o schema padrão da conexão.
    • Parâmetros de entrada:
      • schema (string, opcional): Schema do banco de dados para filtrar tabelas. Padrão: schema padrão da conexão.
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna uma string JSON contendo informações das tabelas (por exemplo, TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TABLE_TYPE).

  • jdbc_filter_table_names

    • Filtra e retorna informações sobre tabelas cujos nomes contêm uma substring específica.
    • Parâmetros de entrada:
      • q (string, obrigatório): A substring a ser pesquisada nos nomes das tabelas.
      • schema (string, opcional): Schema do banco de dados para filtrar tabelas. Padrão: schema padrão da conexão.
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna uma string JSON contendo informações das tabelas correspondentes.

  • jdbc_describe_table

    • Recupera e retorna informações detalhadas sobre as colunas de uma tabela específica.
    • Parâmetros de entrada:
      • schema (string, obrigatório): O nome do schema do banco de dados que contém a tabela.
      • table (string, obrigatório): O nome da tabela a ser descrita.
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna uma string JSON descrevendo as colunas da tabela (por exemplo, COLUMN_NAME, TYPE_NAME, COLUMN_SIZE, IS_NULLABLE).

  • jdbc_query_database

    • Executa uma consulta SQL padrão e retorna os resultados no formato JSON.
    • Parâmetros de entrada:
      • query (string, obrigatório): A string da consulta SQL a ser executada.
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna os resultados da consulta como uma string JSON.

  • jdbc_query_database_md

    • Executa uma consulta SQL padrão e retorna os resultados formatados como uma tabela Markdown.
    • Parâmetros de entrada:
      • query (string, obrigatório): A string da consulta SQL a ser executada.
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna os resultados da consulta como uma string de tabela Markdown.

  • jdbc_query_database_jsonl

    • Executa uma consulta SQL padrão e retorna os resultados no formato JSON Lines (JSONL) (um objeto JSON por linha).
    • Parâmetros de entrada:
      • query (string, obrigatório): A string da consulta SQL a ser executada.
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna os resultados da consulta como uma string JSONL.

  • jdbc_spasql_query

    • Um recurso específico do Virtuoso!
    • Executa uma consulta SPASQL (híbrido SQL/SPARQL) e retorna os resultados.
    • Parâmetros de entrada:
      • query (string, obrigatório): A string da consulta SPASQL.
      • max_rows (number, opcional): Número máximo de linhas a retornar. Padrão: 20.
      • timeout (number, opcional): Tempo limite da consulta em milissegundos. Padrão: 30000 (ou seja, 30 segundos).
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna o resultado da chamada ao procedimento armazenado subjacente (por exemplo, Demo.demo.execute_spasql_query).

  • jdbc_sparql_query

    • Um recurso específico do Virtuoso!
    • Executa uma consulta SPARQL e retorna os resultados.
    • Parâmetros de entrada:
      • query (string, obrigatório): A string da consulta SPARQL.
      • format (string, opcional): Formato de resultado desejado. Padrão: 'json'.
      • timeout (number, opcional): Tempo limite da consulta em milissegundos. Padrão: 30000 (ou seja, 30 segundos).
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna o resultado da chamada à função subjacente (por exemplo, "UB".dba."sparqlQuery").

  • jdbc_virtuoso_support_ai

    • Um recurso específico do Virtuoso!
    • Utiliza uma função de Assistente de IA específica do Virtuoso, passando um prompt e uma chave de API opcional.
    • Parâmetros de entrada:
      • prompt (string, obrigatório): O texto do prompt para a função de IA.
      • api_key (string, opcional): Chave de API para o serviço de IA. Padrão: "none".
      • user (string, opcional): Nome de usuário do banco de dados. Padrão: "demo".
      • password (string, opcional): Senha do banco de dados. Padrão: "demo".
      • url (string, opcional): String de conexão da URL JDBC.
    • Retorna o resultado da chamada à função do Assistente de Suporte de IA (por exemplo, DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI).

Uso Básico e Solução de Problemas

MCP Inspector Conectando ao Driver ODBC do Virtuoso

Para uso básico do cliente MCP e solução de problemas, use o MCP Inspector da seguinte forma:

  1. Instale o MCP Inspector:

    npm install -g @modelcontextprotocol/inspector

  2. Inicie o inspector:

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

Acesse a URL retornada pelo inspector para solucionar problemas nas interações do servidor MCP.

MCP Inspector Conectando a Drivers Adicionais

Para uso básico do cliente MCP e solução de problemas, use o MCP Inspector da seguinte forma:

  1. Instale o(s) driver(es) JDBC, garantindo que seus arquivos JAR estejam registrados na Máquina Virtual Java (JVM) do sistema operacional host por meio de $CLASSPATH. Por exemplo:

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

  2. Inicie o inspector usando os seguintes argumentos de linha de comando:

    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

Exemplo de Uso Baseado nos Drivers Oracle e Informix

  1. Supondo as seguintes informações do driver JDBC:

    • Modelo de URL do Driver JDBC Oracle

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

    • Modelo de URL do Driver JDBC Informix

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

  2. Instale os drivers JDBC Oracle (ojdbc17.jar) e/ou Informix (jdbc-15.0.0.1.1.jar) e garanta que seus arquivos JAR estejam registrados na Máquina Virtual Java (JVM) do sistema operacional host por meio de $CLASSPATH. Por exemplo:

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

  3. Inicie o inspector usando os seguintes argumentos de linha de comando:

    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

  4. Acesse a URL retornada pelo inspector e use a operação jdbc_execute_query para consultar o banco de dados de destino, fornecendo valores reais para os seguintes modelos de campos de entrada:

    • URL JDBC
    • Usuário
    • Senha
    • Consulta