MCP ODBC Server

Acesse fontes de dados acessíveis via ODBC usando um Nome de Fonte de Dados (DSN) configurado.

GitHub
12
Experimente este MCPPatrocinado

Documentação

Servidor MCP OpenLink para ODBC

Este documento cobre a configuração e o uso de um servidor ODBC genérico para o Model Context Protocol (MCP), referido como um servidor mcp-odbc. Ele foi desenvolvido para fornecer aos Modelos de Linguagem de Grande Porte acesso transparente a fontes de dados acessíveis via ODBC, por meio de um Nome de Fonte de Dados configurado para um Conector ODBC específico (também chamado de Driver ODBC).

mcp-client-and-servers|648x499

Implementação do Servidor

Este Servidor MCP para ODBC é uma pequena camada em TypeScript construída sobre o node-odbc. Ele roteia chamadas para o Gerenciador de Driver ODBC local do sistema host via node.js (especificamente usando npx para TypeScript).

Configuração do Ambiente Operacional e Pré-requisitos

Embora os exemplos a seguir sejam orientados ao Conector ODBC Virtuoso, este guia também funcionará com outros Conectores ODBC. Nós fortemente incentivamos contribuições de código e envios de demonstrações de uso relacionadas a outros sistemas de gerenciamento de banco de dados (SGBD) para incorporação neste projeto.

Principais Componentes do Sistema

  1. Verifique a versão do node.js. Se não for 21.1.0 ou superior, atualize ou instale explicitamente usando: 
    nvm install v21.1.0
  2. Instale os componentes MCP usando: 
    npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
  3. Defina a versão do nvm usando: 
    nvm alias default 21.1.0

Instalação

  1. Execute 
    git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git
  2. Mude o diretório 
    cd mcp-odbc-server
  3. Execute 
    npm init -y
  4. Execute 
    npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

Verificações do Ambiente de Execução unixODBC

  1. Verifique a configuração da instalação (ou seja, a localização dos principais arquivos INI) executando: 
    odbcinst -j
  2. Liste os nomes de fontes de dados (DSNs) disponíveis executando: 
    odbcinst -q -s

Variáveis de Ambiente

Como boa prática de segurança, você deve usar o arquivo .env localizado no mesmo diretório que o mcp-ser para definir associações para o Nome da Fonte de Dados ODBC (ODBC_DSN), o Usuário (ODBC_USER), a Senha (ODBC_PWD), o INI ODBC (ODBCINI) e, se você quiser usar a Camada de IA OpenLink (OPAL) via ODBC, a Chave de API do Modelo de Linguagem de Grande Porte (LLM) de destino (API_KEY).

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

Uso

Ferramentas

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

Visão Geral

nomedescrição
get_schemasLista os esquemas de banco de dados acessíveis ao sistema de gerenciamento de banco de dados (SGBD) conectado.
get_tablesLista as tabelas associadas a um esquema de banco de dados selecionado.
describe_tableFornece a descrição de uma tabela associada a um esquema 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.
filter_table_namesLista as tabelas associadas a um esquema de banco de dados selecionado, com base em um padrão de substring do campo de entrada q.
query_databaseExecuta uma consulta SQL e retorna os resultados no formato JSON Lines (JSONL).
execute_queryExecuta uma consulta SQL e retorna os resultados no formato JSON Lines (JSONL).
execute_query_mdExecuta uma consulta SQL e retorna os resultados no formato de tabela Markdown.
spasql_queryExecuta uma consulta SPASQL e retorna os resultados.
sparql_queryExecuta uma consulta SPARQL e retorna os resultados.
virtuoso_support_aiInterage com o Assistente/Agente de Suporte Virtuoso — um recurso específico do Virtuoso para interagir com LLMs

Descrição Detalhada

  • get_schemas

    • Recupera e retorna uma lista de todos os nomes de esquemas 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna uma matriz JSON de strings com os nomes dos esquemas.

  • get_tables

    • Recupera e retorna uma lista contendo informações sobre tabelas em um esquema especificado. Se nenhum esquema for fornecido, usa o esquema padrão da conexão.
    • Parâmetros de entrada:
      • schema (string, opcional): Esquema do banco de dados para filtrar tabelas. Padrão: 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna uma string JSON contendo informações das tabelas (por exemplo, TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TABLE_TYPE).

  • 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): Esquema do banco de dados para filtrar tabelas. Padrão: 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna uma string JSON contendo informações das tabelas correspondentes.

  • 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 esquema 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna uma string JSON descrevendo as colunas da tabela (por exemplo, COLUMN_NAME, TYPE_NAME, COLUMN_SIZE, IS_NULLABLE).

  • 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna os resultados da consulta como uma string JSON.

  • 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna os resultados da consulta como uma string de tabela Markdown.

  • 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna os resultados da consulta como uma string JSONL.

  • spasql_query

    • Executa uma consulta SPASQL (híbrido SQL/SPARQL) e retorna os resultados. Este é um recurso específico do Virtuoso.
    • Parâmetros de entrada:
      • query (string, obrigatório): A string da consulta SPASQL.
      • max_rows (número, opcional): Número máximo de linhas a retornar. Padrão: 20.
      • timeout (número, 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna o resultado da chamada de procedimento armazenado subjacente (por exemplo, Demo.demo.execute_spasql_query).

  • sparql_query

    • Executa uma consulta SPARQL e retorna os resultados. Este é um recurso específico do Virtuoso.
    • Parâmetros de entrada:
      • query (string, obrigatório): A string da consulta SPARQL.
      • format (string, opcional): Formato de resultado desejado. Padrão: 'json'.
      • timeout (número, 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna o resultado da chamada de função subjacente (por exemplo, "UB".dba."sparqlQuery").

  • virtuoso_support_ai

    • Utiliza uma função de Assistente de IA específica do Virtuoso, passando um prompt e uma chave de API opcional. Este é um recurso específico do Virtuoso.
    • 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".
      • dsn (string, opcional): Nome da fonte de dados ODBC. Padrão: "Local Virtuoso".
    • Retorna o resultado da chamada da função do Assistente de Suporte de IA (por exemplo, DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI).

Teste Básico de Instalação e Solução de Problemas

Ferramenta MCP Inspector

Edição Canônica da Ferramenta MCP Inspector

  1. Inicie o inspector a partir do diretório/pasta mcp-server usando o seguinte comando:

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

  2. Clique no botão "Connect" e, em seguida, na aba "Tools" para começar.

    MCP Inspector

Edição OpenLink da Ferramenta MCP Inspector

Esta é uma bifurcação da edição canônica que inclui uma correção de bug de manipulação de JSON relacionada ao uso com este Servidor MCP.

  1. execute 
    git clone git@github.com:OpenLinkSoftware/inspector.git
cd inspector
  2. execute 
    npm run start
  3. Forneça o seguinte valor no campo de entrada Arguments da interface do MCP Inspector de http://localhost:6274 
    tsx /path/to/mcp-odbc-server/src/main.ts
  4. Clique no botão Connect para inicializar sua sessão com o Servidor MCP designado

Compatibilidade Apple Silicon (ARM64) com Problemas do Servidor MCP ODBC

Problema de Conflito Node x86_64 vs arm64

A edição x86_64 em vez de arm64 do node pode estar em vigor, mas a ponte ODBC e o servidor MCP são componentes baseados em arm64.

Você pode resolver esse problema executando as seguintes etapas:

  1. Desinstale a edição x86_64 do node executando: 
     nvm uninstall 21.1.0
  2. Execute o seguinte comando para confirmar que seu shell atual está no modo arm64: 
    arch
    • se isso retornar x86_64, execute o seguinte comando para alterar o modo ativo: 
      arch arm64
  3. Instale a edição arm64 do node executando: 
    nvm install 21.1.0

Incompatibilidade da Camada de Ponte Node para ODBC

Ao tentar usar um Servidor MCP ODBC em máquinas Apple Silicon, você pode encontrar erros de incompatibilidade de arquitetura. Isso ocorre porque o módulo nativo ODBC Node.js (odbc.node) é compilado para a arquitetura ARM64, mas a edição baseada em x86_64 do runtime unixODBC está sendo carregada.

Mensagem de erro típica:

Error: dlopen(...odbc.node, 0x0001): tried: '...odbc.node' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e' or 'arm64'))

Você resolve esse problema executando as seguintes etapas:

  1. Verifique se seu Node.js está rodando no modo ARM64:

    node -p "process.arch"  # Should output: `arm64`

  2. Instale o unixODBC para ARM64:

    # 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. Recompile o módulo ODBC do Node.js para ARM64:

    # 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. Verifique se o módulo agora é ARM64:

    file node_modules/odbc/lib/bindings/napi-v8/odbc.node
# Should show "arm64" instead of "x86_64"

Pontos-chave

  • Tanto o unixODBC quanto o módulo ODBC Node.js devem ser compatíveis com ARM64
  • Usar variáveis de ambiente (export npm_config_arch=arm64) é mais confiável do que comandos npm config
  • Sempre verifique a arquitetura com o comando file ou node -p "process.arch"
  • Ao usar o Homebrew no Apple Silicon, os comandos podem ser prefixados com arch -arm64 para forçar o uso de binários ARM64

Uso do aplicativo MCP

Configuração do Claude Desktop

O caminho para este arquivo de configuração é: ~{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": []
        }
    }
}

Uso do Claude Desktop

  1. Inicie o aplicativo.

  2. Aplique a configuração (acima) via interface do usuário em Configurações | Desenvolvedor.

  3. Certifique-se de ter uma conexão ODBC funcional com um Nome de Fonte de Dados (DSN).

  4. Apresente um prompt solicitando a execução de consulta, por exemplo,

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

    Claude Desktop

Configuração do Cline (Extensão do Visual Studio)

O caminho para este arquivo de configuração é: ~{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": []
    }
  }
}

Uso do Cline (Extensão do Visual Studio)

  1. Use Shift+Command+P para abrir a Paleta de Comandos.

  2. Digite: Cline.

  3. Selecione: Cline View, que abre a interface do Cline na barra lateral do VSCode.

  4. Use o ícone de quatro quadrados para acessar a interface de instalação e configuração dos servidores MCP.

  5. Aplique a Configuração do Cline (acima).

  6. Volte à interface principal da extensão e inicie uma nova tarefa solicitando o processamento do seguinte prompt:

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

    Cline Extension

Configuração do Cursor

Use a engrenagem de configurações para abrir o menu de configuração que inclui o item de menu MCP para registrar e configurar mcp servers.

Uso do Cursor

  1. Use a combinação de teclas Command+I ou Control+I para abrir a Interface de Chat.

  2. Selecione Agent no menu suspenso no canto inferior esquerdo da interface, onde o padrão é Ask.

  3. Insira seu prompt, qualificando o uso do mcp-server for odbc usando o padrão: @odbc {rest-of-prompt}.

  4. Clique em "Aceitar" para executar o prompt.

    Cursor Editor

Relacionados