Mcp Alchemy

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

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 and a host of other SQLAlchemy-compatible databases.

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

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) Examples:
- PostgreSQL: postgresql://user:password@localhost/dbname
- MySQL: mysql+pymysql://user:password@localhost/dbname
- MariaDB: mariadb+pymysql://user:password@localhost/dbname
- SQLite: sqlite:///path/to/database.db
CLAUDE_LOCAL_FILES_PATH: Directory for full result sets (optional)
EXECUTE_QUERY_MAX_CHARS: Maximum output length (optional, default 4000)

Installation

Clone repository:

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

Ensure you have uv

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

Add database to claude_desktop_config.json (see above)

Database Drivers

The following database drivers are included by default:

SQLite: Built into Python, no additional installation needed
MySQL/MariaDB: Via pymysql
PostgreSQL: Via psycopg2-binary

To use other databases supported by SQLAlchemy, install the appropriate driver:

## Microsoft SQL Server
uv pip install pymssql

## Oracle
uv pip install cx_oracle

## Other databases
## See: https://docs.sqlalchemy.org/en/20/dialects/

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.

Contributing

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