MCP Alchemy

By setting the CLAUDE_LOCAL_FILES_PATH environment variable, MCP Alchemy integrates with claude-local-files. This allows Claude to:

• Access complete result sets that exceed the context window.
• Generate detailed reports and visualizations.
• Perform deep analysis on very large datasets.

MCP Alchemy requires uv for installation and running. Use the following command to install it if you haven't already:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

The repository includes a pre-configured tests/claude_desktop_config.json file that contains connection settings for SQLite, MySQL, and PostgreSQL Chinook databases. To use these for testing, copy the file to your Claude Desktop configuration directory.

cp tests/claude_desktop_config.json ~/.config/claude-desktop/config.json

To develop on the project, clone the repository, install dependencies with uv, and install your desired database driver. To run it in Claude Desktop, point the command to the local directory using uv run.

# Setup
git clone git@github.com:runekaagaard/mcp-alchemy.git
cd mcp-alchemy
uv sync
uv pip install psycopg2-binary

# Claude Desktop Config snippet
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-alchemy", "-m", "mcp_alchemy.server", "main"]

To use MCP Alchemy with Claude Desktop, add a configuration entry to your claude_desktop_config.json. You must specify the appropriate database driver using the --with parameter in the args array.

Note: If you encounter a versioning error after a new release, restart the MCP client; it may take up to 600 seconds for the local cache to clear.

After starting the Docker containers, verify that the databases are running and contain data using the following commands:

Check MySQL: Use the mysql client to connect to port 3307 with the chinook user and password.

Check PostgreSQL: Use the psql client to connect to port 5433 with the chinook user and password. Note that the table name "Album" must be double-quoted due to case sensitivity.

# Check MySQL
mysql -h 127.0.0.1 -P 3307 -u chinook -pchinook Chinook -e "SELECT COUNT(*) FROM Album;"

# Check PostgreSQL
PGPASSWORD=chinook psql -h localhost -p 5433 -U chinook chinook_db -c "SELECT COUNT(*) FROM \"Album\";"

To test MCP Alchemy with multiple database engines, use the provided docker-compose configuration. This setup initializes MySQL and PostgreSQL with the Chinook sample database pre-loaded.

1. Navigate to the tests directory.
2. Run docker-compose up -d to start the containers in detached mode.

Created Databases:

• MySQL: Running on port 3307.
• PostgreSQL: Running on port 5433.
• Data: The Chinook sample database is loaded into both.

cd tests
docker-compose up -d

MCP Alchemy uses optimized connection pooling. Default settings include pool_pre_ping=True, pool_size=1, max_overflow=2, pool_recycle=3600, and isolation_level='AUTOCOMMIT'.

You can override these by providing a JSON string in the DB_ENGINE_OPTIONS environment variable.

{
  "DB_ENGINE_OPTIONS": "{\"pool_size\": 5, \"max_overflow\": 10, \"pool_recycle\": 1800}"
}

When executing queries, MCP Alchemy manages large datasets to prevent overwhelming the client:

1. Truncation: Results are formatted vertically. If the formatted output exceeds EXECUTE_QUERY_MAX_CHARS, the output is truncated.
2. Full Result Persistence: If CLAUDE_LOCAL_FILES_PATH is set, the server saves the complete result set as a JSON file named after its SHA256 hash.
3. Artifact Access: Instead of returning the full data in the text response, the tool provides a URL (e.g., https://cdn.jsdelivr.net/pyodide/claude-local-files/{hash}.json) that the client can fetch as an artifact to view the complete dataset.

When running tests, the expected results are:

• 11 tables in each database.
• Identical schema definitions.
• Identical query results across all databases.
• Proper handling of NULL values and formatting.

If results are inconsistent, check the following:

1. Docker container status.
2. Database connection strings.
3. Database initialization scripts.

Add this configuration to claude_desktop_config.json to connect to MS SQL Server. Requires the pymssql driver.

{
  "mcpServers": {
    "my_mssql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.8.1.2602", "--with", "pymssql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mssql+pymssql://user:password@localhost/dbname"
      }
    }
  }
}

Once Claude Desktop is configured, use the following prompt to verify database connectivity, table listing, schema inspection, complex query execution, and cross-database consistency across SQLite, MySQL, and PostgreSQL.

I'd like to explore the Chinook database across different database engines. Let's:

1. First, list all tables in each database (SQLite, MySQL, and PostgreSQL) to verify they're identical
2. Get the schema for the Album and Artist tables from each database
3. Run this query on each database:
   SELECT ar.Name as ArtistName, COUNT(al.AlbumId) as AlbumCount 
   FROM Artist ar 
   LEFT JOIN Album al ON ar.ArtistId = al.ArtistId 
   GROUP BY ar.ArtistId, ar.Name 
   HAVING COUNT(al.AlbumId) > 5 
   ORDER BY AlbumCount DESC;
4. Compare the results - they should be identical across all three databases

Can you help me with this analysis?