ODBC Database Connector MCP server

The OpenLink MCP Server for ODBC provides Large Language Models with transparent access to ODBC-accessible data sources through a Data Source Name configured for a specific ODBC Connector. It functions as a TypeScript layer built on top of node-odbc that routes calls to the host system's local ODBC Driver Manager.

Operating Environment Setup & Prerequisites

Key System Components

1. Check the node.js version. If it's not 21.1.0 or higher, upgrade or install explicitly using:

   nvm install v21.1.0
   

2. Install MCP components using:

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
   

3. Set the nvm version using:

   nvm alias default 21.1.0
   

Installation

1. Clone the repository:

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

2. Change directory:

   cd mcp-odbc-server
   

3. Initialize the package:

   npm init -y
   

4. Install dependencies:

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
   

unixODBC Runtime Environment Checks

1. Check installation configuration (location of key INI files):

   odbcinst -j
   

2. List available data source names (DSNs):

   odbcinst -q -s
   

Environment Variables

Create a .env file in the same directory as the MCP server with the following settings:

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

Available Tools

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

Name	Description
get_schemas	List database schemas accessible to connected database management system
get_tables	List tables associated with a selected database schema
describe_table	Provide the description of a table including column names, data types, etc.
filter_table_names	List tables based on a substring pattern from the q input field
query_database	Execute a SQL query and return results in JSON Lines format
execute_query	Execute a SQL query and return results in JSON Lines format
execute_query_md	Execute a SQL query and return results in Markdown table format
spasql_query	Execute a SPASQL query and return results
sparql_query	Execute a SPARQL query and return results
virtuoso_support_ai	Interact with the Virtuoso Support Assistant/Agent

Tool Details

• get_schemas

  • Retrieves all schema names from the connected database
  • Parameters:
    • user (optional): Database username, defaults to "demo"
    • password (optional): Database password, defaults to "demo"
    • dsn (optional): ODBC data source name, defaults to "Local Virtuoso"
  • Returns: JSON string array of schema names

• get_tables

  • Lists information about tables in a specified schema
  • Parameters:
    • schema (optional): Database schema to filter tables
    • user (optional): Database username
    • password (optional): Database password
    • dsn (optional): ODBC data source name
  • Returns: JSON string containing table information

• filter_table_names

  • Filters tables whose names contain a specific substring
  • Parameters:
    • q (required): The substring to search for in table names
    • schema (optional): Database schema to filter tables
    • user, password, dsn (optional): Connection parameters
  • Returns: JSON string with matching tables information

• describe_table

  • Provides detailed column information for a specific table
  • Parameters:
    • schema (required): Database schema name
    • table (required): Table name to describe
    • user, password, dsn (optional): Connection parameters
  • Returns: JSON string with column details

• query_database

  • Executes a SQL query and returns results in JSON
  • Parameters:
    • query (required): SQL query string
    • user, password, dsn (optional): Connection parameters
  • Returns: Query results as JSON

• query_database_md

  • Executes a SQL query and formats results as Markdown table
  • Parameters:
    • query (required): SQL query string
    • user, password, dsn (optional): Connection parameters
  • Returns: Query results as Markdown table

• query_database_jsonl

  • Executes a SQL query and returns results in JSON Lines format
  • Parameters:
    • query (required): SQL query string
    • user, password, dsn (optional): Connection parameters
  • Returns: Query results as JSONL string

• spasql_query (Virtuoso-specific)

  • Executes a SPASQL (SQL/SPARQL hybrid) query
  • Parameters:
    • query (required): SPASQL query string
    • max_rows (optional): Maximum rows to return, defaults to 20
    • timeout (optional): Query timeout in ms, defaults to 30000
    • user, password, dsn (optional): Connection parameters
  • Returns: Results from the underlying stored procedure call

• sparql_query (Virtuoso-specific)

  • Executes a SPARQL query
  • Parameters:
    • query (required): SPARQL query string
    • format (optional): Result format, defaults to 'json'
    • timeout (optional): Query timeout in ms, defaults to 30000
    • user, password, dsn (optional): Connection parameters
  • Returns: Results from the underlying function call

• virtuoso_support_ai (Virtuoso-specific)

  • Interacts with Virtuoso's AI Assistant
  • Parameters:
    • prompt (required): Prompt text for the AI function
    • api_key (optional): API key for the AI service
    • user, password, dsn (optional): Connection parameters
  • Returns: Results from the AI Support Assistant function call

Testing and Troubleshooting

MCP Inspector Tool

Standard MCP Inspector

1. Start the inspector from the mcp-server directory:

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

2. Click "Connect" and then "Tools" to begin using the interface.

OpenLink MCP Inspector Edition

1. Clone the repository:

   git clone [email protected]:OpenLinkSoftware/inspector.git
   cd inspector
   

2. Start the inspector:

   npm run start
   

3. In the "Arguments" field at http://localhost:6274, enter:

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

4. Click "Connect" to initialize your session.

Apple Silicon (ARM64) Compatibility Issues

Node Architecture Mismatch

If you encounter architecture conflicts:

1. Uninstall the x86_64 edition of Node:

   nvm uninstall 21.1.0
   

2. Confirm your shell is in arm64 mode:

   arch
   

   If it returns x86_64, switch to arm64:

   arch arm64
   

3. Install the arm64 edition of Node:

   nvm install 21.1.0
   

ODBC Bridge Layer Incompatibility

If you see "incompatible architecture" errors:

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

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

2. Install unixODBC for ARM64:

   which brew  # Should point to /opt/homebrew/bin/brew
   brew uninstall --force unixodbc
   arch -arm64 brew install unixodbc
   

3. Rebuild the Node.js ODBC module:

   cd /path/to/mcp-odbc-server
   rm -rf node_modules/odbc
   export npm_config_arch=arm64
   npm install odbc --build-from-source
   

4. Verify the module architecture:

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

Using MCP with Various Applications

Claude Desktop Configuration

Create or edit ~/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": []
        }
    }
}

Cline (VS Code Extension) Configuration

Create or edit ~/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": []
    }
  }
}

Using the MCP Server

With Claude Desktop

1. Start the application
2. Apply the configuration via Settings > Developer interface
3. Present a query prompt, for example:

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

With Cline (VS Code Extension)

1. Open Command Palette (Shift+Command+P)
2. Type "Cline" and select "Cline View"
3. Configure the MCP server using the four-squares icon
4. Start a new task with a query prompt, for example:

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

With Cursor Editor

1. Open the configuration menu and register the MCP server
2. Use Command+I or Control+I to open the Chat Interface
3. Select "Agent" from the dropdown (default is "Ask")
4. Format your prompt using: @odbc {your-query-prompt}
5. Click "Accept" to execute

Related Resources

• MCP Inspector Usage Screencast: https://www.openlinksw.com/data/screencasts/mcp-inspector-odbc-sparql-spasql-demo-1.mp4
• Claude Desktop Usage Screencast: https://www.openlinksw.com/data/screencasts/claude-odbc-mcp-sql-spasql-demo-1.mp4
• Cline VS Code Extension Usage: https://www.openlinksw.com/data/screencasts/cline-vscode-mcp-odbc-sql-spasql-1.mp4
• Cursor Editor Usage: https://www.openlinksw.com/data/screencasts/cursor-odbc-mcp-sql-spasql-demo-1.mp4

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "odbc" '{"command":"node","args":["node_modules/.bin/tsx","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":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "odbc": {
            "command": "node",
            "args": [
                "node_modules/.bin/tsx",
                "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": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "odbc": {
            "command": "node",
            "args": [
                "node_modules/.bin/tsx",
                "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": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect