Introduction

by OpenLinkSoftware

12 stars
380 downloads
Not rated
GitHub

About

Typescript based Model Context Procotol (MCP) Server for Open Database Connectivity (ODBC)

Details

Author
OpenLinkSoftware
GitHub stars
12
Downloads
380
Categories
Database, Other

Jump to

- Provides generic ODBC data access for LLMs via MCP.
- Supports SQL, SPASQL, and SPARQL queries.
- Offers schema and table inspection tools.
- Includes a Virtuoso-specific AI assistant tool.
- Returns query results in JSON, JSONL, or Markdown format.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Introduction
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Operating Environment Set Up Prerequisites

While the examples that follow are oriented toward the Virtuoso ODBC Connector, this guide will also work with other ODBC Connectors. Westronglyencourage code contributions and submissions of usage demos related to other database management systems (DBMS) for incorporation into this project.
- Check thenode.jsversion. If it's not21.1.0or higher, upgrade or install explicitly using:

nvm install v21.1.0

npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

- Run

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

npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

- Check installation configuration (i.e., location of key INI files) by running:

odbcinst -j

As good security practice, you should use the.envfile situated in the same directory as themcp-serto set bindings for the ODBC Data Source Name (ODBC_DSN), the User (ODBC_USER), the Password (ODBC_PWD), the ODBC INI (ODBCINI), and, if you want to use the OpenLink AI Layer (OPAL) via ODBC, the target Large Language Model (LLM) API Key (API_KEY).

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

After successful installation, the following tools will be available to MCP client applications.

- Retrieve and return a list of all schema names from the connected database.
- Input parameters:

- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Retrieve and return a list containing information about tables in a specified schema. If no schema is provided, uses the connection's default schema.
- Input parameters:

- schema(string, optional): Database schema to filter tables. Defaults to connection default.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Filters and returns information about tables whose names contain a specific substring.
- Input parameters:

- q(string, required): The substring to search for within table names.
- schema(string, optional): Database schema to filter tables. Defaults to connection default.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Retrieve and return detailed information about the columns of a specific table.
- Input parameters:

- schema(string, required): The database schema name containing the table.
- table(string, required): The name of the table to describe.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Execute a standard SQL query and return the results in JSON format.
- Input parameters:

- query(string, required): The SQL query string to execute.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Execute a standard SQL query and return the results formatted as a Markdown table.
- Input parameters:

- query(string, required): The SQL query string to execute.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Execute a standard SQL query and return the results in JSON Lines (JSONL) format (one JSON object per line).
- Input parameters:

- query(string, required): The SQL query string to execute.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Execute a SPASQL (SQL/SPARQL hybrid) query return results. This is a Virtuoso-specific feature.
- Input parameters:

- query(string, required): The SPASQL query string.
- max_rows(number, optional): Maximum number of rows to return. Defaults to20.
- timeout(number, optional): Query timeout in milliseconds. Defaults to30000, i.e., 30 seconds.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Execute a SPARQL query and return results. This is a Virtuoso-specific feature.
- Input parameters:

- query(string, required): The SPARQL query string.
- format(string, optional): Desired result format. Defaults to'json'.
- timeout(number, optional): Query timeout in milliseconds. Defaults to30000, i.e., 30 seconds.
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

- Utilizes a Virtuoso-specific AI Assistant function, passing a prompt and optional API key. This is a Virtuoso-specific feature.
- Input parameters:

- prompt(string, required): The prompt text for the AI function.
- api_key(string, optional): API key for the AI service. Defaults to"none".
- user(string, optional): Database username. Defaults to"demo".
- password(string, optional): Database password. Defaults to"demo".
- dsn(string, optional): ODBC data source name. Defaults to"Local Virtuoso".

Basic Installation Testing Troubleshooting

-

Start the inspector from the mcp-server directory/folder using the following command:

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

Click on the "Connect" button, then click on the "Tools" tab to get started.

This is a fork of the canonical edition that includes a JSON handling bug fix related to use with this MCP Server.
- run

git clone git@github.com:OpenLinkSoftware/inspector.git cd inspector

tsx /path/to/mcp-odbc-server/src/main.ts

Cline Visual Studio Extension Configuration

The path for this config file is:~{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": [] } } }

-

Use Shift+Command+Pto open the Command Palette.

Select:Cline View, which opens the Cline UI in the VSCode sidebar.

Use the four-squares icon to access the UI for installing and configuring MCP servers.

Return to the extension's main UI and start a new task requesting processing of the following prompt:

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

Use the settings gear to open the configuration menu that includes the MCP menu item for registering and configuringmcp servers.
-

Use the Command+Ior Control+Ikey combination to open the Chat Interface.

SelectAgentfrom the drop-down at the bottom left of the UI, where the default isAsk.

Enter your prompt, qualifying the use of themcp-server for odbcusing the pattern:@odbc {rest-of-prompt}.

Click on "Accept" to execute the prompt.

- MCP Inspector Usage Screencast
- Basic Claude Desktop Usage Screencast
- Basic Cline Visual Studio Code Extension Usage Screencast
- Basic Cursor Editor Usage Screencast

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Query and analyze data with MotherDuck and local DuckDB

A collection of tools for managing the platform, addressing data quality and reading and writing to Teradata Database.

A read-only MCP server for Avro data sources, powered by the CData JDBC Driver.

Run SQL queries on data in Amazon S3 using AWS Athena.

Interact with Bauplan data tables and run queries.

Production-grade MCP server for Databricks: SQL Warehouses, Jobs API, multi-workspace support.

Visual no-code generator that turns any database into multiple scoped MCP servers — one per access group, with PII masking and fail-closed query scoping built in.

A read-only MCP server by CData that enables LLMs to query live data from EnterpriseDB databases.

A read-only MCP server for MySQL, enabling LLMs to query live data using the CData JDBC Driver.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "introduction": {
            "ODBC": {
                "command": "/Users/kidehen/.nvm/versions/node/v21.1.0/bin/node",
                "args": [
                    "/Users/kidehen/Documents/Management/Development/modelcontextprotocol/mcp-odbc-server/node_modules/.bin/tsx",
                    "/Users/kidehen/Documents/Management/Development/modelcontextprotocol/mcp-odbc-server/main.ts"
                ],
                "env": {
                    "ODBCINI": "/Library/ODBC/odbc.ini",
                    "NODE_VERSION": "v21.1.0",
                    "PATH": "/Users/kidehen/.nvm/versions/node/v21.1.0/bin:${PATH}"
                },
                "disabled": false,
                "autoApprove": []
            }
        }
    }
}

McpServers

{
    "ODBC": {
        "command": "/Users/kidehen/.nvm/versions/node/v21.1.0/bin/node",
        "args": [
            "/Users/kidehen/Documents/Management/Development/modelcontextprotocol/mcp-odbc-server/node_modules/.bin/tsx",
            "/Users/kidehen/Documents/Management/Development/modelcontextprotocol/mcp-odbc-server/main.ts"
        ],
        "env": {
            "ODBCINI": "/Library/ODBC/odbc.ini",
            "NODE_VERSION": "v21.1.0",
            "PATH": "/Users/kidehen/.nvm/versions/node/v21.1.0/bin:${PATH}"
        },
        "disabled": false,
        "autoApprove": []
    }
}

Apple Silicon (ARM64) Compatibility with MCP ODBC Server Issues

Node x86_64 vs arm64 Conflict Issue

The x86_64 rather than arm64 edition of node may be in place, but the ODBC bridge and MCP server are arm64-based components.

You can solve this problem by performing the following steps:

1. Uninstall the x86_64 edition of node by running:

    nvm uninstall 21.1.0

2. Run the following command to confirm your current shell is in arm64 mode:
   arch

- if that returns x86_64, then run the following command to change the active mode:
     arch arm64

3. Install the arm64 edition of node by running:
   nvm install 21.1.0

Node to ODBC Bridge Layer Incompatibility

When attempting to use a Model Context Protocol (MCP) ODBC Server on Apple Silicon machines, you may encounter architecture mismatch errors. These occur because the Node.js ODBC native module (odbc.node) is compiled for ARM64 architecture, but the x86_64-based edition of the unixODBC runtime is being loaded.

Typical error message:

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

You solve this problem by performing the following steps:

1. Verify your Node.js is running in ARM64 mode:

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

2. Install unixODBC for 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. Rebuild the Node.js ODBC module for 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. Verify the module is now ARM64:

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

Key Points

- Both unixODBC and the Node.js ODBC module must be ARM64-compatible
- Using environment variables (export npm_config_arch=arm64) is more reliable than npm config commands
- Always verify architecture with the file command or node -p "process.arch"
- When using Homebrew on Apple Silicon, commands can be prefixed with arch -arm64 to force use of ARM64 binaries

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "introduction": {
            "ODBC": {
                "command": "/Users/kidehen/.nvm/versions/node/v21.1.0/bin/node",
                "args": [
                    "/Users/kidehen/Documents/Management/Development/modelcontextprotocol/mcp-odbc-server/node_modules/.bin/tsx",
                    "/Users/kidehen/Documents/Management/Development/modelcontextprotocol/mcp-odbc-server/main.ts"
                ],
                "env": {
                    "ODBCINI": "/Library/ODBC/odbc.ini",
                    "NODE_VERSION": "v21.1.0",
                    "PATH": "/Users/kidehen/.nvm/versions/node/v21.1.0/bin:${PATH}"
                },
                "disabled": false,
                "autoApprove": []
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other