📌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.

MCP Alchemy connects Claude Desktop directly to your databases, enabling users to:

• Explore and understand database structures
• Write and validate SQL queries
• Display relationships between tables
• Analyze large datasets and create reports

Supported Databases

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

API

Tools

• all_table_names

  • Returns all table names in the database.
  • No input required.

  users, orders, products, categories
  

• filter_table_names

  • Finds tables matching a substring.
  • Input: q (string).

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

• schema_definitions

  • Gets detailed schema for specified tables.
  • Input: table_names (string[]).

  users:
      id: INTEGER, primary key, autoincrement
      email: VARCHAR(255), nullable
  

• execute_query

  • Executes SQL query with vertical output format.
  • Inputs:
    • query (string): SQL query.
    • params (object, optional): Query parameters.

  1. row
  id: 123
  name: John Doe
  

  • Features include smart truncation, full result set access, and clean NULL value display.

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my_database": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-alchemy", "run", "server.py"],
      "env": {
        "DB_URL": "mysql+pymysql://root:secret@localhost/databasename"
      }
    }
  }
}

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)

Installation

1. Clone the repository:

   git clone https://github.com/runekaagaard/mcp-alchemy.git
   

2. Ensure you have uv installed:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Add your database to claude_desktop_config.json.

Database Drivers

Included database drivers:

• SQLite: Built into Python
• MySQL/MariaDB: Via pymysql
• PostgreSQL: Via psycopg2-binary

To use other databases, install the appropriate driver:

# Microsoft SQL Server
uv pip install pymssql

# Oracle
uv pip install cx_oracle

Claude Local Files

With claude-local-files configured:

• Access complete result sets beyond Claude's context window.
• Generate reports and visualizations.
• Perform analysis on large datasets.

This integration activates when CLAUDE_LOCAL_FILES_PATH is set.

Contributing

Contributions are welcome! You can:

• Open issues for bugs or features.
• Submit pull requests.
• Enhance documentation.

Your insights help improve database interaction with Claude.

License

Mozilla Public License Version 2.0