📌Overview

Purpose: MCP Alchemy aims to seamlessly connect Claude Desktop with various databases, enhancing database exploration, management, and reporting capabilities.

Overview: MCP Alchemy serves as a powerful integration tool that allows users to engage with their databases interactively through Claude Desktop. It supports different SQL databases, providing advanced functionalities for query writing, data analysis, and visualization without any known bugs.

Key Features:

Database Exploration: Easily explore database structures, including table relationships and schema definitions, to gain an in-depth understanding of the data.
SQL Query Assistance: Write, validate, and execute SQL queries with enhanced output formatting, smart truncation for large results, and integration for accessing complete datasets.

MCP Alchemy

Status: Works great and is in daily use without any known bugs.
Status2: Package added to PyPI with updated usage instructions. Please report any issues.

MCP Alchemy connects Claude Desktop directly to your databases, allowing it to:

Help explore and understand your database structure
Assist in writing and validating SQL queries
Display relationships between tables
Analyze large datasets and create reports
Analyze and create artifacts for very large datasets using claude-local-files

Works with PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, and many other SQLAlchemy-compatible databases.

Installation

Ensure you have uv installed:

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

Usage with Claude Desktop

Add to your claude_desktop_config.json. Include the appropriate database driver in the --with parameter.

Note: After a new version release, local cache clearing might cause a versioning error for up to 600 seconds. Restarting the MCP client resolves this.

SQLite (built into Python)

{
  "mcpServers": {
    "my_sqlite_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.04.16.110003",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "sqlite:///path/to/database.db"
      }
    }
  }
}

PostgreSQL

{
  "mcpServers": {
    "my_postgres_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.04.16.110003", "--with", "psycopg2-binary",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "postgresql://user:password@localhost/dbname"
      }
    }
  }
}

MySQL/MariaDB

{
  "mcpServers": {
    "my_mysql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.04.16.110003", "--with", "pymysql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mysql+pymysql://user:password@localhost/dbname"
      }
    }
  }
}

Microsoft SQL Server

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

Oracle

{
  "mcpServers": {
    "my_oracle_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.04.16.110003", "--with", "cx_oracle",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "oracle+cx_oracle://user:password@localhost/dbname"
      }
    }
  }
}

CrateDB

{
  "mcpServers": {
    "my_cratedb": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.04.16.110003", "--with", "sqlalchemy-cratedb>=0.42.0.dev1",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "crate://user:password@localhost:4200/?schema=testdrive"
      }
    }
  }
}

For connecting to CrateDB Cloud, use a URL like:
crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true

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)

API

Tools

all_table_names
Returns all table names in the database as a comma-separated list.
filter_table_names
Finds tables matching a substring.
Input: q (string)
Returns matching table names.
schema_definitions
Provides detailed schema for specified tables, including column names and types, primary keys, foreign key relationships, and nullable flags.
execute_query
Executes a SQL query with vertical output format.
Inputs:
- query (string)
- params (object, optional)
  Returns results in a clean vertical format with features including smart truncation, full result access via claude-local-files integration, clean NULL display, ISO formatted dates, and clear row separation.

Claude Local Files

When claude-local-files is configured (by setting CLAUDE_LOCAL_FILES_PATH), MCP Alchemy can:

Access complete result sets beyond Claude's context window
Generate detailed reports and visualizations
Perform deep analysis on large datasets
Export results for further processing

Developing

Clone the repository, install dependencies, and your database drivers:

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

Then update claude_desktop_config.json:

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

Contributing

Contributions are welcome! You can:

Report bugs or suggest features
Submit pull requests
Improve documentation or share usage examples
Ask questions and share experiences

Help make database interaction with Claude even better.

License

Mozilla Public License Version 2.0

My Other LLM Projects

MCP Redmine - Claude Desktop managing Redmine projects and issues.
MCP Notmuch Sendmail - Email assistant for Claude Desktop using notmuch.
Diffpilot - Multi-column git diff viewer with file grouping and tagging.
Claude Local Files - Access local files in Claude Desktop artifacts.