Skip to main content
Glama
Sign In
enesjakozh

MCP Alchemy

by runekaagaard
GitHub
Python
Mozilla Public License 2.0
159
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

  • Integrates with claude-local-files from GitHub for handling large datasets and creating artifacts

  • Provides connectivity to MariaDB databases for SQL query execution, schema inspection, and data exploration

  • Allows direct interaction with MySQL databases to execute queries, examine table structures, and analyze data

MCP Alchemy

Status: Works great and is in daily use without any known bugs.

Status2: I just added the package to PyPI and updated the usage instructions. Please report any issues :)

Let Claude be your database expert! MCP Alchemy connects Claude Desktop directly to your databases, allowing it to:

  • Help you explore and understand your database structure
  • Assist in writing and validating SQL queries
  • Displays relationships between tables
  • Analyze large datasets and create reports
  • Claude Desktop Can analyse and create artifacts for very large datasets using claude-local-files.

Works with PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, and a host of 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. You need to add the appropriate database driver in the --with parameter.

Note: After a new version release there might be a period of up to 600 seconds while the cache clears locally cached causing uv to raise a versioning error. Restarting the MCP client once again solves the error.

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
    • Return all table names in the database
    • No input required
    • Returns comma-separated list of tables
    users, orders, products, categories
  • filter_table_names
    • Find tables matching a substring
    • Input: q (string)
    • Returns matching table names
    Input: "user" Returns: "users, user_roles, user_permissions"
  • schema_definitions
    • Get detailed schema for specified tables
    • Input: table_names (string[])
    • Returns table definitions including:
      • Column names and types
      • Primary keys
      • Foreign key relationships
      • Nullable flags
    users: id: INTEGER, primary key, autoincrement email: VARCHAR(255), nullable created_at: DATETIME Relationships: id -> orders.user_id
  • execute_query
    • Execute SQL query with vertical output format
    • Inputs:
      • query (string): SQL query
      • params (object, optional): Query parameters
    • Returns results in clean vertical format:
    1. row id: 123 name: John Doe created_at: 2024-03-15T14:30:00 email: NULL Result: 1 rows
    • Features:
      • Smart truncation of large results
      • Full result set access via claude-local-files integration
      • Clean NULL value display
      • ISO formatted dates
      • Clear row separation

Claude Local Files

When claude-local-files is configured:

  • 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

The integration automatically activates when CLAUDE_LOCAL_FILES_PATH is set.

Developing

First clone the github repository, install the dependencies and your database driver(s) of choice:

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

Then set this in claude_desktop_config.json:

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

Contributing

Contributions are warmly welcomed! Whether it's bug reports, feature requests, documentation improvements, or code contributions - all input is valuable. Feel free to:

  • Open an issue to report bugs or suggest features
  • Submit pull requests with improvements
  • Enhance documentation or share your usage examples
  • Ask questions and share your experiences

The goal is to make database interaction with Claude even better, and your insights and contributions help achieve that.

License

Mozilla Public License Version 2.0

My Other LLM Projects

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

Connects Claude Desktop directly to databases, allowing it to explore database structures, write SQL queries, analyze datasets, and create reports through an API layer with tools for table exploration and query execution.

  1. Installation
    1. Usage with Claude Desktop
      1. SQLite (built into Python)
      2. PostgreSQL
      3. MySQL/MariaDB
      4. Microsoft SQL Server
      5. Oracle
      6. CrateDB
    2. Environment Variables
      1. API
        1. Tools
      2. Claude Local Files
        1. Developing
          1. Contributing
            1. License
              1. My Other LLM Projects

                Related Resources

                Appeared in Searches

                ID: axb5hvasqx