Purpose
MCP Alchemy is an MCP (Model Context Protocol) server that provides LLMs with access to relational databases and related knowledge. It allows clients such as Claude Desktop to connect directly to databases, act as a database expert, assist in exploring and understanding database structures, writing and validating SQL queries, displaying relationships between tables, analyzing large datasets, and creating reports. The project is actively maintained and used daily, and test versions are released to PyPI with git tags.
Supported databases
Supports PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, Vertica, and a large number of other SQLAlchemy-compatible databases. The SQLite driver is built into Python and requires no additional installation.
Installation and configuration
uv must be installed first. When using Claude Desktop, add the configuration to claude_desktop_config.json, and add the corresponding database driver in the --with parameter. For example, SQLite (built into Python) and Microsoft SQL Server each have their own configuration examples. To connect to CrateDB Cloud, you can use a URL of the form crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true.
Container images are published to the GitHub Container Registry, with common database drivers preinstalled (PostgreSQL, MySQL/MariaDB, MS SQL Server, Oracle). You can also build it yourself with docker build -t ghcr.io/runekaagaard/mcp-alchemy .
By default, the server uses stdio communication, and it can also serve corresponding clients over HTTP.
Note: After a new version is released, there may be up to 600 seconds during which local cache clearing causes uv to report a version error; simply restart the MCP client again to resolve it.
Environment variables
- DB_URL: SQLAlchemy database URL (required)
- CLAUDE_LOCAL_FILES_PATH: directory for storing full result sets (optional)
- EXECUTE_QUERY_MAX_CHARS: maximum output length (optional, default 4000)
- DB_ENGINE_OPTIONS: JSON string containing additional SQLAlchemy engine options (optional)
Connection pool
MCP Alchemy uses a connection pool optimized for long-running MCP servers, with the following default settings: pool_pre_ping=True (test the connection before use, handling database timeouts and network issues), pool_size=1 (maintain 1 persistent connection; MCP servers usually handle one request at a time), max_overflow=2 (allow up to 2 additional connections for bursts), pool_recycle=3600 (refresh connections older than 1 hour to prevent timeout issues), isolation_level='AUTOCOMMIT' (ensure each query is automatically committed).
These defaults are suitable for most databases and can be overridden via DB_ENGINE_OPTIONS. For databases with aggressive timeout settings (such as MySQL's default of 8 hours), the combination of pool_pre_ping and pool_recycle ensures reliable connections.
Main tools
- all_table_names: returns all table names in the database, requires no input, and returns a comma-separated list of tables.
- filter_table_names: finds tables matching a substring, takes q (string) as input, and returns matching table names.
- schema_definitions: gets the detailed schema of specified tables, takes table_names (array of strings) as input, and returns table definitions, including column names and types, primary keys, foreign key relationships, and nullable flags.
- execute_query: executes a SQL query and returns the results in a vertical output format. Inputs are query (string) and optional params (object). Features include: intelligent truncation for large results, access to full result sets via claude-local-files integration, clear NULL value display, ISO-format dates, and explicit row separators.
Claude Local Files integration
When CLAUDE_LOCAL_FILES_PATH is configured, it is possible to access full result sets that exceed Claude's context window, generatingDetailed reports and visualizations, in-depth analysis of large datasets, export results for further processing. Integration is automatically activated after setting this environment variable.
Running from source
First clone the GitHub repository, install dependencies and the selected database driver, then make the corresponding settings in claude_desktop_config.json.
License
Mozilla Public License Version 2.0.
Contributions are welcome: reporting bugs, proposing feature requests, improving documentation, or submitting code can all be done by opening an issue or pull request.
