mcp-odbc

Introducción

Este documento describe la configuración y el uso de un servidor ODBC genérico para el Protocolo de Contexto de Modelo (MCP), denominado servidor mcp-odbc . Se desarrolló para proporcionar a los Modelos de Lenguaje Grandes acceso transparente a fuentes de datos accesibles mediante ODBC mediante un nombre de fuente de datos configurado para un conector ODBC específico (también denominado controlador ODBC).

Implementación del servidor

Este servidor MCP para ODBC es una pequeña capa de TypeScript construida sobre node-odbc . Enruta las llamadas al administrador de controladores ODBC local del sistema host mediante node.js (específicamente, usando npx para TypeScript).

Configuración y requisitos previos del entorno operativo

Aunque los ejemplos siguientes están orientados al Conector ODBC de Virtuoso, esta guía también es compatible con otros conectores ODBC. Recomendamos encarecidamente las contribuciones de código y el envío de demostraciones de uso relacionadas con otros sistemas de gestión de bases de datos (SGBD) para su incorporación en este proyecto.

Componentes clave del sistema

1. Comprueba la versión node.js Si no es 21.1.0 o superior, actualízala o instálala explícitamente usando:
   nvm install v21.1.0
2. Instalar componentes MCP usando:
   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
3. Establezca la versión nvm usando:
   nvm alias default 21.1.0

Instalación

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

Comprobaciones del entorno de ejecución de unixODBC

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

Variables de entorno

Como buena práctica de seguridad, debe utilizar el archivo .env ubicado en el mismo directorio que mcp-ser para establecer enlaces para el nombre de origen de datos ODBC ( ODBC_DSN ), el usuario ( ODBC_USER ), la contraseña ( ODBC_PWD ), el ODBC INI ( ODBCINI ) y, si desea utilizar OpenLink AI Layer (OPAL) a través de ODBC, la clave API del modelo de lenguaje grande (LLM) de destino ( API_KEY ).

Uso

Herramientas

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

Descripción general

Descripción detallada

• get_schemas
  • Recupere y devuelva 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. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve una matriz de cadenas JSON de nombres de 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, se utiliza el esquema predeterminado de la conexión.
  • Parámetros de entrada:
    • schema (cadena, opcional): Esquema de base de datos para filtrar tablas. El valor predeterminado es el valor de conexión.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve una cadena JSON que contiene información de la tabla (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, obligatoria): la subcadena que se buscará dentro de los nombres de las tablas.
    • schema (cadena, opcional): Esquema de base de datos para filtrar tablas. El valor predeterminado es el valor de conexión.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve una cadena JSON que contiene información para las tablas coincidentes.
• describe_table
  • Recupere y devuelva 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, obligatoria): el nombre de la tabla a describir.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "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, obligatoria): la cadena de consulta SQL que se ejecutará.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve los resultados de la consulta como una cadena JSON.
• query_database_md
  • Ejecute una consulta SQL estándar y devuelva los resultados formateados como una tabla Markdown.
  • Parámetros de entrada:
    • query (cadena, obligatoria): la cadena de consulta SQL que se ejecutará.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "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 de líneas JSON (JSONL) (un objeto JSON por línea).
  • Parámetros de entrada:
    • query (cadena, obligatoria): la cadena de consulta SQL que se ejecutará.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve los resultados de la consulta como una cadena JSONL.
• spasql_query
  • Ejecutar una consulta SPASQL (SQL/SPARQL híbrido) y devolver resultados. Esta función es específica de Virtuoso.
  • Parámetros de entrada:
    • query (cadena, obligatoria): la cadena de consulta SPASQL.
    • max_rows (número, opcional): Número máximo de filas a devolver. El valor predeterminado es 20 .
    • timeout (número, opcional): Tiempo de espera de la consulta en milisegundos. El valor predeterminado es 30000 , es decir, 30 segundos.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve el resultado de la llamada al procedimiento almacenado subyacente (por ejemplo, Demo.demo.execute_spasql_query ).
• sparql_query
  • Ejecutar una consulta SPARQL y devolver resultados. Esta es una función específica de Virtuoso.
  • Parámetros de entrada:
    • query (cadena, obligatoria): la cadena de consulta SPARQL.
    • format (cadena, opcional): formato del resultado deseado. El valor predeterminado es 'json' .
    • timeout (número, opcional): Tiempo de espera de la consulta en milisegundos. El valor predeterminado es 30000 , es decir, 30 segundos.
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve el resultado de la llamada de función subyacente (por ejemplo, "UB".dba."sparqlQuery" ).
• virtuoso_support_ai
  • Utiliza una función del Asistente de IA específica de Virtuoso, que envía un mensaje y una clave API opcional. Esta función es específica de Virtuoso.
  • Parámetros de entrada:
    • prompt (cadena, obligatorio): el texto de solicitud para la función AI.
    • api_key (cadena, opcional): Clave de API para el servicio de IA. El valor predeterminado es "none" .
    • user (cadena, opcional): nombre de usuario de la base de datos. El valor predeterminado es "demo" .
    • password (cadena, opcional): Contraseña de la base de datos. El valor predeterminado es "demo" .
    • dsn (cadena, opcional): nombre de la fuente de datos ODBC. El valor predeterminado es "Local Virtuoso" .
  • Devuelve el resultado de la llamada a la función AI Support Assistant (por ejemplo, DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI ).

Pruebas de instalación básicas y resolución de problemas

Herramienta de inspección MCP

Edición de la herramienta Canonical MCP Inspector

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 "Conectar", luego haga clic en la pestaña "Herramientas" para comenzar.

Edición de la herramienta de inspección 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 relacionados con el uso con este servidor MCP.

1. correr
   git clone git@github.com:OpenLinkSoftware/inspector.git cd inspector
2. correr
   npm run start
3. Proporcione el siguiente valor en el campo de entrada Arguments de la interfaz de usuario de Inspectores de MCP 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

Problemas de compatibilidad de Apple Silicon (ARM64) con el servidor ODBC MCP

Problema de conflicto entre nodos x86_64 y arm64

Es posible que esté instalada la edición x86_64 en lugar de arm64 del node , pero el puente ODBC y el servidor MCP son componentes basados en arm64.

Puedes solucionar este problema realizando los siguientes pasos:

1. Desinstale la edición x86_64 del 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, ejecute el siguiente comando para cambiar el modo activo:
     arch arm64
3. Instale la edición arm64 del node ejecutando:
   nvm install 21.1.0

Incompatibilidad entre el nodo y la capa de puente ODBC

Al intentar usar un servidor ODBC de Protocolo de Contexto de Modelo (MCP) en equipos Apple Silicon, pueden producirse errores de incompatibilidad de arquitectura. Esto ocurre porque el módulo nativo ODBC de Node.js ( odbc.node ) está compilado para la arquitectura ARM64, pero se está cargando la edición x86_64 del entorno de ejecución unixODBC.

Mensaje de error típico:

Puedes 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. Instalar 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. Reconstruir 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 de Node.js deben ser compatibles con ARM64
• El uso de variables de entorno ( export npm_config_arch=arm64 ) es más confiable que los comandos de configuración de npm
• Verifique siempre la arquitectura con el comando file o node -p "process.arch"
• Al usar Homebrew en Apple Silicon, los comandos pueden prefijarse con arch -arm64 para forzar el uso de binarios ARM64

Uso de la aplicación MCP

Configuración del escritorio de Claude

La ruta para este archivo de configuración es: ~{username}/Library/Application Support/Claude/claude_desktop_config.json .

Uso del escritorio de Claude

1. Inicie la aplicación.
2. Aplicar la configuración (desde arriba) a través de Configuración | Interfaz de usuario para desarrolladores.
3. Asegúrese de tener una conexión ODBC en funcionamiento a un nombre de fuente de datos (DSN).
4. Presentar un mensaje solicitando la ejecución de una consulta, por ejemplo,
   Execute the following query: SELECT TOP * from Demo..Customers

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

La ruta para este archivo de configuración es: ~{username}/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Uso de Cline (extensión de Visual Studio)

1. Utilice Shift+Comando+P para abrir la paleta de comandos.
2. Escriba: Cline .
3. Seleccionar: Vista Cline, que abre la interfaz de usuario de Cline en la barra lateral de VSCode.
4. Utilice el icono de cuatro cuadrados para acceder a la interfaz de usuario para instalar y configurar servidores MCP.
5. Aplicar la configuración de Cline (de arriba).
6. Regrese a la interfaz de usuario principal de la extensión y comience una nueva tarea solicitando el procesamiento del siguiente mensaje:
   "Execute the following query: SELECT TOP 5 * from Demo..Customers"

Configuración del cursor

Utilice 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 del cursor

1. Utilice 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 de usuario, donde el valor predeterminado es Ask .
3. Ingrese su mensaje, calificando el uso del mcp-server for odbc usando el patrón: @odbc {rest-of-prompt} .
4. Haga clic en “Aceptar” para ejecutar el mensaje.

Relacionado

• Captura de pantalla del uso del inspector MCP
• Uso básico de Claude Desktop Screencast
• Uso básico de la extensión Cline de Visual Studio Code en pantalla
• Uso básico del editor de cursores: captura de pantalla