runekaagaard/mcp-alchemy

**Status: Actively maintained and in daily use. Tested releases are published to PyPI with git tags, and issues and pull requests are triaged regularly.**
Let Claude be your database expert! MCP Alchemy connects Claude Desktop directly to your databases, allowing it to:
- Help you explore and understand your database structure
- Assist in writing and validating SQL queries
- Displays relationships between tables
- Analyze large datasets and create reports
- Claude Desktop Can analyse and create artifacts for very large datasets using claude-local-files.
Works with PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, Vertica,
and a host of other SQLAlchemy-compatible databases.
Installation
Ensure you have uv installed:
Usage with Claude Desktop
Add to your claude_desktop_config.json. You need to add the appropriate database driver in the --with parameter.
_Note: After a new version release there might be a period of up to 600 seconds while the cache clears locally
cached causing uv to raise a versioning error. Restarting the MCP client once again solves the error._
SQLite (built into Python)
PostgreSQL
MySQL/MariaDB
Microsoft SQL Server
Oracle
CrateDB
For connecting to CrateDB Cloud, use a URL like
crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true.
Vertica
Docker
A container image is published to GitHub Container Registry with common database drivers
(PostgreSQL, MySQL/MariaDB, MS SQL Server, Oracle) preinstalled:
Or build it yourself with docker build -t ghcr.io/runekaagaard/mcp-alchemy .
Transports
By default the server speaks stdio. It can also serve over HTTP for clients that connect that way:
Environment Variables
- DB_URL: SQLAlchemy database URL (required)
- CLAUDE_LOCAL_FILES_PATH: Directory for 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 Pooling
MCP Alchemy uses connection pooling optimized for long-running MCP servers. The default settings are:
- pool_pre_ping=True: Tests connections before use to handle database timeouts and network issues
- pool_size=1: Maintains 1 persistent connection (MCP servers typically handle one request at a time)
- max_overflow=2: Allows up to 2 additional connections for burst capacity
- pool_recycle=3600: Refreshes connections older than 1 hour (prevents timeout issues)
- isolation_level='AUTOCOMMIT': Ensures each query commits automatically
These defaults work well for most databases, but you can override them via DB_ENGINE_OPTIONS:
For databases with aggressive timeout settings (like MySQL's 8-hour default), the combination of pool_pre_ping and pool_recycle ensures reliable connections.
API
Tools
- **all_table_names**
- Return all table names in the database
- No input required
- Returns comma-separated list of tables
- **filter_table_names**
- Find tables matching a substring
- Input: q (string)
- Returns matching table names
- **schema_definitions**
- Get detailed schema for specified tables