mcp-alchemy

MCP Alchemy is a Python-based MCP server that connects Claude Desktop to your databases, enabling you to explore database structures, validate and compose SQL queries, and analyze large datasets. The server exposes a set of API tools such as all_table_names, filter_table_names, schema_definitions, and execute_query, which you can call from Claude Desktop or via the claude-local-files integration for large result sets. To use it, configure Claude Desktop to point at your mcp-alchemy package via uvx, providing the appropriate database driver in the --with parameter depending on your database (e.g., psycopg2-binary for PostgreSQL, pymysql for MySQL). You can also adjust connection pooling and engine options with DB_ENGINE_OPTIONS to optimize performance for long-running queries. When CLAUDE_LOCAL_FILES_PATH is set, you gain access to complete result sets and deeper analysis through claude-local-files.

Prerequisites:

• Python runtime installed and uvx available (via uv).
• Access to install Python packages (PyPI package mcp-alchemy).

Installation steps:

1. Install uv if you haven't already: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Install the MCP Alchemy package from PyPI (via uvx): uvx install mcp-alchemy
3. Start the MCP Alchemy server (example using uvx to run the package): uvx --from mcp-alchemy==2025.8.15.91819 --refresh-package mcp-alchemy mcp-alchemy
4. Configure Claude Desktop to connect using claude_desktop_config.json, referencing the server and the appropriate DB driver in the --with argument for your database.

Note: If you update to a new version, you may experience a short cache warm-up period. Restarting the MCP client can resolve versioning errors during that window.

• The DB_URL environment variable is required for most database connections. It should be a SQLAlchemy database URL (see SQLAlchemy docs).
• You can tune connection pooling via DB_ENGINE_OPTIONS, for example: { "DB_ENGINE_OPTIONS": "{"pool_size": 5, "max_overflow": 10, "pool_recycle": 1800}" }.
• CLAUDE_LOCAL_FILES_PATH enables export and deeper analysis via claude-local-files; ensure the path is accessible to the MCP Alchemy process.
• If you encounter a cache/versioning error after a new release, restart the MCP client to re-cache the package.