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
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
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:
- 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
