Unleash Claude's Database Prowess: MCP Alchemy - Your Gateway to Seamless LLM-Database Integration

Current Status: Production-Ready and Battle-Tested

Latest Update: Now Available on PyPI! Please Report Any Issues.

Transform Claude into your personal database virtuoso! MCP Alchemy bridges the gap between Claude Desktop and your databases, empowering it to:

• Effortlessly Navigate Database Structures: Gain a comprehensive understanding of your database schema with Claude's intuitive guidance.
• Craft and Validate SQL with Precision: Let Claude assist you in writing, debugging, and optimizing SQL queries for peak performance.
• Visualize Table Relationships: Uncover hidden connections and dependencies between tables through clear and concise relationship diagrams.
• Analyze Massive Datasets with Ease: Empower Claude to analyze vast datasets and generate insightful reports, unlocking valuable business intelligence.
• Leverage claude-local-files for Unbounded Data Analysis: Seamlessly integrate with claude-local-files to overcome context window limitations and analyze extremely large datasets.

MCP Alchemy boasts compatibility with a wide array of databases, including:

• PostgreSQL
• MySQL
• MariaDB
• SQLite
• Oracle
• MS SQL Server
• CrateDB
• ...and any other database adhering to the SQLAlchemy dialect specifications.

Installation: A Streamlined Setup

Ensure you have uv installed for optimal package management:

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

Integration with Claude Desktop: Configuration Made Simple

Integrate MCP Alchemy into your claude_desktop_config.json file. Remember to include the appropriate database driver using the --with parameter.

Example Configurations:

SQLite (Native Python Support)

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

PostgreSQL

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

MySQL/MariaDB

{
  "mcpServers": {
    "my_mysql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.04.09.091234", "--with", "pymysql", "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.09.091234", "--with", "pymssql", "mcp-alchemy"],
      "env": {
        "DB_URL": "mssql+pymssql://user:password@localhost/dbname"
      }
    }
  }
}

Oracle

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

CrateDB

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

For CrateDB Cloud connections, utilize a URL structure similar to: crate://user:[email protected]:4200?ssl=true.

Environment Variables: Fine-Tuning Your Integration

• DB_URL: The essential SQLAlchemy database URL defining your database connection.
• CLAUDE_LOCAL_FILES_PATH: (Optional) Specifies the directory for storing full result sets, enabling analysis beyond Claude's context window.
• EXECUTE_QUERY_MAX_CHARS: (Optional) Sets the maximum output length for query results (default: 4000 characters).

API: A Toolkit for Database Interaction

Available Tools:

• all_table_names:

  • Purpose: Retrieves all table names within the connected database.
  • Input: None
  • Output: A comma-separated list of table names.
  • Example:

    users, orders, products, categories
    

• filter_table_names:

  • Purpose: Identifies tables whose names contain a specific substring.
  • Input: q (string) - The substring to search for.
  • Output: A comma-separated list of matching table names.
  • Example:

    Input: "user"
    Returns: "users, user_roles, user_permissions"
    

• schema_definitions:

  • Purpose: Provides detailed schema information for specified tables.
  • Input: table_names (string[]) - An array of table names.
  • Output: Table definitions including:
    • Column names and data types
    • Primary key constraints
    • Foreign key relationships
    • Nullability flags
  • Example:

    users:
        id: INTEGER, primary key, autoincrement
        email: VARCHAR(255), nullable
        created_at: DATETIME
    
        Relationships:
          id -> orders.user_id
    

• execute_query:

  • Purpose: Executes an SQL query and presents the results in a clear, vertical format.
  • Inputs:
    • query (string): The SQL query to execute.
    • params (object, optional): Query parameters (if required).
  • Output: Results displayed in a vertical format for readability:

    1. row
    id: 123
    name: John Doe
    created_at: 2024-03-15T14:30:00
    email: NULL
    
    Result: 1 rows
    

  • Key Features:
    • Intelligent truncation of large result sets to fit within context limits.
    • Seamless integration with claude-local-files for accessing complete result sets.
    • Clear representation of NULL values.
    • ISO 8601 formatted dates for consistency.
    • Distinct row separation for enhanced readability.

Claude Local Files Integration: Unleashing the Power of Large Datasets

When integrated with claude-local-files:

• Access Complete Result Sets: Overcome Claude's context window limitations and work with full datasets.
• Generate Detailed Reports and Visualizations: Create comprehensive reports and visualizations for in-depth analysis.
• Perform Deep Analysis on Large Datasets: Unlock the potential of your data through advanced analytical capabilities.
• Export Results for Further Processing: Export data for use in other tools and workflows.

The integration is automatically enabled when the CLAUDE_LOCAL_FILES_PATH environment variable is set.

Contributing: Shape the Future of MCP Alchemy

Your contributions are highly valued! We encourage you to:

• Report bugs and suggest new features by opening issues.
• Submit pull requests with code improvements and enhancements.
• Improve the documentation and share your usage examples.
• Ask questions and share your experiences with the community.

Together, we can make database interaction with Claude even more powerful and intuitive.

My Other LLM Projects

• MCP Redmine - Empower Claude Desktop to manage your Redmine projects and issues.
• MCP Notmuch Sendmail - Enhance Claude Desktop with email assistance using notmuch.
• Diffpilot - A multi-column git diff viewer with file grouping and tagging capabilities.
• Claude Local Files - Enable access to local files within Claude Desktop artifacts.