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 (o controlador) ODBC específico.

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 demostraciones de uso relacionadas con otros sistemas de gestión de bases de datos para su incorporación en este proyecto.

Componentes clave del sistema

1. Verifique la versión de node.js; si no es 21.1.0, 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 nvm usando: nvm alias default 21.1.0

Instalación

1. Ejecute git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git
2. Cambiar directorio cd mcp-odbc-server
3. Ejecute npm init -y
4. Agregue la entrada "type":"module" al archivo package.json
5. Ejecute 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 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 la clave API del modelo de lenguaje grande de destino (si desea utilizar OpenLink AI Layer (OPAL) a través de ODBC), el nombre de la fuente de datos ODBC (ODBC_DSN), el usuario (ODBC_USER), la contraseña (ODBC_PWD) y el INI ODBC (ODBCINI).

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

• obtener_esquemas
  • 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 "Virtuoso local".
  • Devuelve una matriz de cadenas JSON de nombres de esquemas.
• obtener_tablas
  • 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 "Virtuoso local".
  • Devuelve una cadena JSON que contiene información de la tabla (por ejemplo, TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TABLE_TYPE).
• nombres_de_tabla_de_filtro
  • 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 "Virtuoso local".
  • Devuelve una cadena JSON que contiene información para las tablas coincidentes.
• describe_tabla
  • 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 "Virtuoso local".
  • Devuelve una cadena JSON que describe las columnas de la tabla (por ejemplo, COLUMN_NAME, TYPE_NAME, COLUMN_SIZE, IS_NULLABLE).
• base de datos de consultas
  • 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 "Virtuoso local".
  • Devuelve los resultados de la consulta como una cadena JSON.
• consulta_base_de_datos_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 "Virtuoso local".
  • Devuelve los resultados de la consulta como una cadena de tabla Markdown.
• consulta_base_de_datos_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 "Virtuoso local".
  • Devuelve los resultados de la consulta como una cadena JSONL.
• consulta_spasql
  • 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.
    • 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 "Virtuoso local".
  • Devuelve el resultado de la llamada al procedimiento almacenado subyacente (por ejemplo, Demo.demo.execute_spasql_query ).
• consulta sparql
  • 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.
    • 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 "Virtuoso local".
  • 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. Su valor predeterminado es "ninguna".
    • 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 "Virtuoso local".
  • 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

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.

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. Iniciar 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 principal de la extensión e inicie una nueva tarea solicitando el procesamiento del siguiente mensaje: "Ejecute la siguiente consulta: 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 or 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, ya que 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