mcp-sqlalchemy

This MCP server provides ODBC access via SQLAlchemy for connecting to Virtuoso or other supported DBMS backends. It exposes a set of tools that let clients retrieve schemas, tables, and detailed table descriptions, as well as execute queries and stored procedures where supported. The server is built with FastAPI, pyodbc, and SQLAlchemy, enabling SQL-based interactions over ODBC through a RESTful interface that can be proxied or consumed by clients such as Claude or other MCP clients. Typical usage involves establishing an ODBC-like connection string (via the provided URLs) and selecting from the available tools to inspect database metadata or run queries. The included toolset covers: listing schemas (podbc_get_schemas), listing tables (podbc_get_tables), describing tables (podbc_describe_table), filtering tables by name (podbc_filter_table_names), and executing standard SQL queries in JSONL or Markdown formats (podbc_query_database, podbc_query_database_md, podbc_query_database_jsonl). It also supports Virtuoso-specific SPASQL/SPARQL interactions where applicable (podbc_spasql_query and podbc_sparql_query).

Prerequisites:

• Python 3.8+ and pip
• Git
• uv installed (pip install uv)

Step-by-step:

1. Install uv if not already installed: pip install uv

2. Clone the repository: git clone https://github.com/OpenLinkSoftware/mcp-sqlalchemy-server.git cd mcp-sqlalchemy-server

3. Set up environment variables (example .env): ODBC_DSN=VOS ODBC_USER=dba ODBC_PASSWORD=dba API_KEY=your-api-key

4. Start the MCP server using uv (example): uv --directory /path/to/mcp-sqlalchemy-server run mcp-sqlalchemy-server

5. Verify the server is running by hitting the API endpoint (default FastAPI port 8000) or by following any project-specific startup logs.

Note: Depending on your deployment method, you may use a Docker image, npx-based workflow, or other runners. The configuration example in Claude Desktop can be adapted to your environment by pointing to the local server executable and supplying the necessary environment variables.

Tips and common issues:

• Ensure the ODBC DSN (ODBC_DSN) is correctly configured on the host where the MCP server runs. Test connectivity with an odbcinst utility before enabling the MCP endpoints.
• If you encounter authentication or DSN binding errors, verify that ODBC_USER and ODBC_PASSWORD are correct and that the DSN name matches the one configured in ~/.odbc.ini or system DSNs.
• When using Virtuoso, some operations (like executing stored procedures) may require specific permissions or backend capabilities; consult the backend docs for any limitations.
• For production deployments, consider securing the API with API_KEY and restricting network access to trusted clients.
• The server supports multiple query output formats; use JSONL for streaming or large results, and Markdown for human-readable reports.
• If deploying via Claude Desktop, ensure the claude_desktop_config.json references the correct path to your server and that environment variables are properly mapped.