MCP ODBC Server

Accede a fuentes de datos accesibles mediante ODBC usando un Nombre de Origen de Datos (DSN) configurado.

GitHub
12
Prueba este MCPPatrocinado

Documentación

Servidor MCP OpenLink para ODBC

Este documento cubre la configuración y el uso de un servidor ODBC genérico para el Protocolo de Contexto de Modelos (MCP), denominado servidor mcp-odbc. Ha sido desarrollado para proporcionar a los Modelos de Lenguaje de Gran Escala acceso transparente a fuentes de datos accesibles vía ODBC mediante un Nombre de Fuente de Datos configurado para un Conector ODBC específico (también llamado Controlador ODBC).

mcp-client-and-servers|648x499

Implementación del Servidor

Este Servidor MCP para ODBC es una pequeña capa en TypeScript construida sobre node-odbc. Enruta las llamadas al Administrador de Controladores ODBC local del sistema anfitrión a través de node.js (específicamente usando npx para TypeScript).

Configuración del Entorno Operativo y Requisitos Previos

Aunque los ejemplos que siguen están orientados al Conector ODBC de Virtuoso, esta guía también funcionará con otros Conectores ODBC. Recomendamos encarecidamente contribuciones de código y envíos de demostraciones de uso relacionadas con otros sistemas de gestión de bases de datos (DBMS) para su incorporación a este proyecto.

Componentes Clave del Sistema

  1. Verifique la versión de node.js. Si no es 21.1.0 o superior, actualice o instale explícitamente usando: 
    nvm install v21.1.0
  2. Instale los componentes MCP usando: 
    npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
  3. Establezca la versión de nvm usando: 
    nvm alias default 21.1.0

Instalación

  1. Ejecute 
    git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git
  2. Cambie de directorio 
    cd mcp-odbc-server
  3. Ejecute 
    npm init -y
  4. Ejecute 
    npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

Verificaciones del Entorno de Ejecución unixODBC

  1. Verifique la configuración de instalación (es decir, la ubicación de los archivos INI clave) ejecutando: 
    odbcinst -j
  2. Liste los nombres de fuentes de datos (DSN) disponibles ejecutando: 
    odbcinst -q -s

Variables de Entorno

Como buena práctica de seguridad, debe usar el archivo .env situado en el mismo directorio que el mcp-ser para establecer los enlaces del Nombre de Fuente de Datos ODBC (ODBC_DSN), el Usuario (ODBC_USER), la Contraseña (ODBC_PWD), el INI de ODBC (ODBCINI) y, si desea usar la Capa de IA de OpenLink (OPAL) vía ODBC, la Clave API del Modelo de Lenguaje de Gran Escala (LLM) objetivo (API_KEY).

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

Uso

Herramientas

Tras una instalación exitosa, las siguientes herramientas estarán disponibles para las aplicaciones cliente MCP.

Resumen

nombredescripción
get_schemasLista los esquemas de base de datos accesibles para el sistema de gestión de bases de datos (DBMS) conectado.
get_tablesLista las tablas asociadas con un esquema de base de datos seleccionado.
describe_tableProporciona 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.
filter_table_namesLista las tablas asociadas con un esquema de base de datos seleccionado, basándose en un patrón de subcadena del campo de entrada q.
query_databaseEjecuta una consulta SQL y devuelve los resultados en formato JSON Lines (JSONL).
execute_queryEjecuta una consulta SQL y devuelve los resultados en formato JSON Lines (JSONL).
execute_query_mdEjecuta una consulta SQL y devuelve los resultados en formato de tabla Markdown.
spasql_queryEjecuta una consulta SPASQL y devuelve los resultados.
sparql_queryEjecuta una consulta SPARQL y devuelve los resultados.
virtuoso_support_aiInteractúa con el Asistente/Agente de Soporte de Virtuoso — una característica específica de Virtuoso para interactuar con LLMs

Descripción Detallada

  • 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. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve una matriz JSON de cadenas con los nombres de los esquemas.

  • get_tables

    • Recupera y devuelve una lista con información sobre las tablas de 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 la base de datos para filtrar tablas. Valor predeterminado: esquema de la conexión.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve una cadena JSON con información de las tablas (por ejemplo, TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TABLE_TYPE).

  • filter_table_names

    • Filtra y devuelve información sobre las tablas cuyos nombres contienen una subcadena específica.
    • Parámetros de entrada:
      • q (cadena, obligatorio): La subcadena a buscar dentro de los nombres de las tablas.
      • schema (cadena, opcional): Esquema de la base de datos para filtrar tablas. Valor predeterminado: esquema de la conexión.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve una cadena JSON con información de las tablas coincidentes.

  • describe_table

    • Recupera y devuelve información detallada sobre las columnas de una tabla específica.
    • Parámetros de entrada:
      • schema (cadena, obligatorio): El nombre del esquema de la base de datos que contiene la tabla.
      • table (cadena, obligatorio): El nombre de la tabla a describir.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve una cadena JSON que describe las columnas de la tabla (por ejemplo, COLUMN_NAME, TYPE_NAME, COLUMN_SIZE, IS_NULLABLE).

  • query_database

    • Ejecuta una consulta SQL estándar y devuelve los resultados en formato JSON.
    • Parámetros de entrada:
      • query (cadena, obligatorio): La cadena de consulta SQL a ejecutar.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve los resultados de la consulta como una cadena JSON.

  • query_database_md

    • Ejecuta una consulta SQL estándar y devuelve los resultados formateados como una tabla Markdown.
    • Parámetros de entrada:
      • query (cadena, obligatorio): La cadena de consulta SQL a ejecutar.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve los resultados de la consulta como una cadena de tabla Markdown.

  • 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, obligatorio): La cadena de consulta SQL a ejecutar.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve los resultados de la consulta como una cadena JSONL.

  • spasql_query

    • Ejecuta una consulta SPASQL (híbrido SQL/SPARQL) y devuelve los resultados. Esta es una característica específica de Virtuoso.
    • Parámetros de entrada:
      • query (cadena, obligatorio): La cadena de consulta SPASQL.
      • max_rows (número, opcional): Número máximo de filas a devolver. Valor predeterminado: 20.
      • timeout (número, opcional): Tiempo de espera de la consulta en milisegundos. Valor predeterminado: 30000, es decir, 30 segundos.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve el resultado de la llamada al procedimiento almacenado subyacente (por ejemplo, Demo.demo.execute_spasql_query).

  • sparql_query

    • Ejecuta una consulta SPARQL y devuelve los resultados. Esta es una característica específica de Virtuoso.
    • Parámetros de entrada:
      • query (cadena, obligatorio): La cadena de consulta SPARQL.
      • format (cadena, opcional): Formato de resultado deseado. Valor predeterminado: 'json'.
      • timeout (número, opcional): Tiempo de espera de la consulta en milisegundos. Valor predeterminado: 30000, es decir, 30 segundos.
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve el resultado de la llamada a la función subyacente (por ejemplo, "UB".dba."sparqlQuery").

  • virtuoso_support_ai

    • Utiliza una función de Asistente de IA específica de Virtuoso, pasando un prompt y una clave API opcional. Esta es una característica específica de Virtuoso.
    • Parámetros de entrada:
      • prompt (cadena, obligatorio): El texto del prompt para la función de IA.
      • api_key (cadena, opcional): Clave API para el servicio de IA. Valor predeterminado: "none".
      • user (cadena, opcional): Nombre de usuario de la base de datos. Valor predeterminado: "demo".
      • password (cadena, opcional): Contraseña de la base de datos. Valor predeterminado: "demo".
      • dsn (cadena, opcional): Nombre de la fuente de datos ODBC. Valor predeterminado: "Local Virtuoso".
    • Devuelve el resultado de la llamada a la función del Asistente de Soporte de IA (por ejemplo, DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI).

Pruebas Básicas de Instalación y Solución de Problemas

Herramienta Inspector MCP

Edición Canónica de la Herramienta Inspector MCP

  1. Inicie el inspector desde el directorio/carpeta mcp-server usando el siguiente comando:

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

  2. Haga clic en el botón "Connect" y luego en la pestaña "Tools" para comenzar.

    MCP Inspector

Edición de la Herramienta Inspector MCP de OpenLink

Esta es una bifurcación de la edición canónica que incluye una corrección de errores de manejo de JSON relacionada con el uso de este Servidor MCP.

  1. Ejecute 
    git clone git@github.com:OpenLinkSoftware/inspector.git
cd inspector
  2. Ejecute 
    npm run start
  3. Proporcione el siguiente valor en el campo de entrada Arguments de la interfaz de usuario de MCP Inspectors desde http://localhost:6274 
    tsx /path/to/mcp-odbc-server/src/main.ts
  4. Haga clic en el botón Connect para inicializar su sesión con el Servidor MCP designado

Compatibilidad de Apple Silicon (ARM64) con Problemas del Servidor MCP ODBC

Problema de Conflicto Node x86_64 vs arm64

La edición x86_64 en lugar de arm64 de node puede estar instalada, pero el puente ODBC y el servidor MCP son componentes basados en arm64.

Puede resolver este problema realizando los siguientes pasos:

  1. Desinstale la edición x86_64 de node ejecutando: 
     nvm uninstall 21.1.0
  2. Ejecute el siguiente comando para confirmar que su shell actual está en modo arm64: 
    arch
    • si eso devuelve x86_64, entonces ejecute el siguiente comando para cambiar el modo activo: 
      arch arm64
  3. Instale la edición arm64 de node ejecutando: 
    nvm install 21.1.0

Incompatibilidad de la Capa Puente Node a ODBC

Al intentar usar un Servidor ODBC del Protocolo de Contexto de Modelos (MCP) en máquinas Apple Silicon, puede encontrar errores de discrepancia de arquitectura. Estos ocurren porque el módulo nativo ODBC Node.js (odbc.node) está compilado para la arquitectura ARM64, pero se está cargando la edición basada en x86_64 del runtime unixODBC.

Mensaje de error típico:

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

Puede resolver este problema realizando los siguientes pasos:

  1. Verifique que su Node.js se está ejecutando en modo ARM64:

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

  2. Instale 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. Reconstruya el módulo ODBC de 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 que el módulo ahora sea ARM64:

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

Puntos clave

  • Tanto unixODBC como el módulo ODBC Node.js deben ser compatibles con ARM64
  • El uso de variables de entorno (export npm_config_arch=arm64) es más fiable que los comandos npm config
  • Verifique siempre la arquitectura con el comando file o node -p "process.arch"
  • Al usar Homebrew en Apple Silicon, los comandos se pueden prefijar con arch -arm64 para forzar el uso de binarios ARM64

Uso de la aplicación MCP

Configuración de Claude Desktop

La ruta de este archivo de configuración es: ~{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 de Claude Desktop

  1. Inicie la aplicación.

  2. Aplique la configuración (de arriba) mediante la interfaz de usuario Configuración | Desarrollador.

  3. Asegúrese de tener una conexión ODBC funcional a un Nombre de origen de datos (DSN).

  4. Presente un prompt solicitando la ejecución de una consulta, por ejemplo,

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

    Claude Desktop

Configuración de Cline (Extensión de Visual Studio)

La ruta de este archivo de configuración es: ~{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 de Cline (Extensión de Visual Studio)

  1. Use Shift+Command+P para abrir la Paleta de comandos.

  2. Escriba: Cline.

  3. Seleccione: Cline View, que abre la interfaz de Cline en la barra lateral de VSCode.

  4. Use el icono de cuatro cuadrados para acceder a la interfaz de instalación y configuración de servidores MCP.

  5. Aplique la configuración de Cline (de arriba).

  6. Vuelva a la interfaz principal de la extensión e inicie una nueva tarea solicitando el procesamiento del siguiente prompt:

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

    Cline Extension

Configuración de Cursor

Use el engranaje de configuración para abrir el menú de configuración que incluye el elemento de menú MCP para registrar y configurar mcp servers.

Uso de Cursor

  1. Use la combinación de teclas Command+I o Control+I para abrir la interfaz de chat.

  2. Seleccione Agent en el menú desplegable en la parte inferior izquierda de la interfaz, donde el valor predeterminado es Ask.

  3. Ingrese su prompt, calificando el uso del mcp-server for odbc usando el patrón: @odbc {rest-of-prompt}.

  4. Haga clic en "Aceptar" para ejecutar el prompt.

    Cursor Editor

Relacionados