MCP Alchemy

1# MCP Alchemy
2 
3<a href="https://www.pulsemcp.com/servers/runekaagaard-alchemy"><img src="https://www.pulsemcp.com/badge/top-pick/runekaagaard-alchemy" width="400" alt="PulseMCP Badge"></a>
4 
5**Status: Works great and is in daily use without any known bugs.**
6 
7**Status2: I just added the package to PyPI and updated the usage instructions. Please report any issues :)**
8 
9Let Claude be your database expert! MCP Alchemy connects Claude Desktop directly to your databases, allowing it to:
10 
11- Help you explore and understand your database structure
12- Assist in writing and validating SQL queries
13- Displays relationships between tables
14- Analyze large datasets and create reports
15- Claude Desktop Can analyse and create artifacts for very large datasets using [claude-local-files](https://github.com/runekaagaard/claude-local-files).
16 
17Works with PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, Vertica,
18and a host of other [SQLAlchemy-compatible](https://docs.sqlalchemy.org/en/20/dialects/) databases.
19 
20![MCP Alchemy in action](https://raw.githubusercontent.com/runekaagaard/mcp-alchemy/refs/heads/main/screenshot.png)
21 
22## Installation
23 
24Ensure you have uv installed:
25```bash
26# Install uv if you haven't already
27curl -LsSf https://astral.sh/uv/install.sh | sh
28```
29 
30## Usage with Claude Desktop
31 
32Add to your `claude_desktop_config.json`. You need to add the appropriate database driver in the ``--with`` parameter.
33 
34_Note: After a new version release there might be a period of up to 600 seconds while the cache clears locally 
35cached causing uv to raise a versioning error. Restarting the MCP client once again solves the error._
36 
37### SQLite (built into Python)
38```json
39{
40  "mcpServers": {
41    "my_sqlite_db": {
42      "command": "uvx",
43      "args": ["--from", "mcp-alchemy==2025.8.15.91819",
44               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
45      "env": {
46        "DB_URL": "sqlite:////absolute/path/to/database.db"
47      }
48    }
49  }
50}
51```
52 
53### PostgreSQL
54```json
55{
56  "mcpServers": {
57    "my_postgres_db": {
58      "command": "uvx",
59      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "psycopg2-binary",
60               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
61      "env": {
62        "DB_URL": "postgresql://user:password@localhost/dbname"
63      }
64    }
65  }
66}
67```
68 
69### MySQL/MariaDB
70```json
71{
72  "mcpServers": {
73    "my_mysql_db": {
74      "command": "uvx",
75      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "pymysql",
76               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
77      "env": {
78        "DB_URL": "mysql+pymysql://user:password@localhost/dbname"
79      }
80    }
81  }
82}
83```
84 
85### Microsoft SQL Server
86```json
87{
88  "mcpServers": {
89    "my_mssql_db": {
90      "command": "uvx",
91      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "pymssql",
92               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
93      "env": {
94        "DB_URL": "mssql+pymssql://user:password@localhost/dbname"
95      }
96    }
97  }
98}
99```
100 
101### Oracle
102```json
103{
104  "mcpServers": {
105    "my_oracle_db": {
106      "command": "uvx",
107      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "oracledb",
108               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
109      "env": {
110        "DB_URL": "oracle+oracledb://user:password@localhost/dbname"
111      }
112    }
113  }
114}
115```
116 
117### CrateDB
118```json
119{
120  "mcpServers": {
121    "my_cratedb": {
122      "command": "uvx",
123      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "sqlalchemy-cratedb>=0.42.0.dev1",
124               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
125      "env": {
126        "DB_URL": "crate://user:password@localhost:4200/?schema=testdrive"
127      }
128    }
129  }
130}
131```
132For connecting to CrateDB Cloud, use a URL like
133`crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true`.
134 
135### Vertica
136```json
137{
138  "mcpServers": {
139    "my_vertica_db": {
140      "command": "uvx",
141      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "vertica-python",
142               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
143      "env": {
144        "DB_URL": "vertica+vertica_python://user:password@localhost:5433/dbname",
145        "DB_ENGINE_OPTIONS": "{\"connect_args\": {\"ssl\": false}}"
146      }
147    }
148  }
149}
150```
151 
152## Environment Variables
153 
154- `DB_URL`: SQLAlchemy [database URL](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls) (required)
155- `CLAUDE_LOCAL_FILES_PATH`: Directory for full result sets (optional)
156- `EXECUTE_QUERY_MAX_CHARS`: Maximum output length (optional, default 4000)
157- `DB_ENGINE_OPTIONS`: JSON string containing additional SQLAlchemy engine options (optional)
158 
159## Connection Pooling
160 
161MCP Alchemy uses connection pooling optimized for long-running MCP servers. The default settings are:
162 
163- `pool_pre_ping=True`: Tests connections before use to handle database timeouts and network issues
164- `pool_size=1`: Maintains 1 persistent connection (MCP servers typically handle one request at a time)
165- `max_overflow=2`: Allows up to 2 additional connections for burst capacity
166- `pool_recycle=3600`: Refreshes connections older than 1 hour (prevents timeout issues)
167- `isolation_level='AUTOCOMMIT'`: Ensures each query commits automatically
168 
169These defaults work well for most databases, but you can override them via `DB_ENGINE_OPTIONS`:
170 
171```json
172{
173  "DB_ENGINE_OPTIONS": "{\"pool_size\": 5, \"max_overflow\": 10, \"pool_recycle\": 1800}"
174}
175```
176 
177For databases with aggressive timeout settings (like MySQL's 8-hour default), the combination of `pool_pre_ping` and `pool_recycle` ensures reliable connections.
178 
179## API
180 
181### Tools
182 
183- **all_table_names**
184  - Return all table names in the database
185  - No input required
186  - Returns comma-separated list of tables
187  ```
188  users, orders, products, categories
189  ```
190 
191- **filter_table_names**
192  - Find tables matching a substring
193  - Input: `q` (string)
194  - Returns matching table names
195  ```
196  Input: "user"
197  Returns: "users, user_roles, user_permissions"
198  ```
199 
200- **schema_definitions**
201  - Get detailed schema for specified tables
202  - Input: `table_names` (string[])
203  - Returns table definitions including:
204    - Column names and types
205    - Primary keys
206    - Foreign key relationships
207    - Nullable flags
208  ```
209  users:
210      id: INTEGER, primary key, autoincrement
211      email: VARCHAR(255), nullable
212      created_at: DATETIME
213      
214      Relationships:
215        id -> orders.user_id
216  ```
217 
218- **execute_query**
219  - Execute SQL query with vertical output format
220  - Inputs:
221    - `query` (string): SQL query
222    - `params` (object, optional): Query parameters
223  - Returns results in clean vertical format:
224  ```
225  1. row
226  id: 123
227  name: John Doe
228  created_at: 2024-03-15T14:30:00
229  email: NULL
230 
231  Result: 1 rows
232  ```
233  - Features:
234    - Smart truncation of large results
235    - Full result set access via [claude-local-files](https://github.com/runekaagaard/claude-local-files) integration
236    - Clean NULL value display
237    - ISO formatted dates
238    - Clear row separation
239 
240## Claude Local Files
241 
242When [claude-local-files](https://github.com/runekaagaard/claude-local-files) is configured:
243 
244- Access complete result sets beyond Claude's context window
245- Generate detailed reports and visualizations
246- Perform deep analysis on large datasets
247- Export results for further processing
248 
249The integration automatically activates when `CLAUDE_LOCAL_FILES_PATH` is set.
250 
251## Developing
252 
253First clone the github repository, install the dependencies and your database driver(s) of choice:
254 
255```
256git clone git@github.com:runekaagaard/mcp-alchemy.git
257cd mcp-alchemy
258uv sync
259uv pip install psycopg2-binary
260```
261 
262Then set this in claude_desktop_config.json:
263 
264```
265...
266"command": "uv",
267"args": ["run", "--directory", "/path/to/mcp-alchemy", "-m", "mcp_alchemy.server", "main"],
268...
269```
270 
271## My Other LLM Projects
272 
273- **[MCP Redmine](https://github.com/runekaagaard/mcp-redmine)** - Let Claude Desktop manage your Redmine projects and issues.
274- **[MCP Notmuch Sendmail](https://github.com/runekaagaard/mcp-notmuch-sendmail)** - Email assistant for Claude Desktop using notmuch.
275- **[Diffpilot](https://github.com/runekaagaard/diffpilot)** - Multi-column git diff viewer with file grouping and tagging.
276- **[Claude Local Files](https://github.com/runekaagaard/claude-local-files)** - Access local files in Claude Desktop artifacts.
277 
278## MCP Directory Listings
279 
280MCP Alchemy is listed in the following MCP directory sites and repositories:
281 
282- [PulseMCP](https://www.pulsemcp.com/servers/runekaagaard-alchemy)
283- [Glama](https://glama.ai/mcp/servers/@runekaagaard/mcp-alchemy)
284- [MCP.so](https://mcp.so/server/mcp-alchemy)
285- [MCP Archive](https://mcp-archive.com/server/mcp-alchemy)
286- [Playbooks MCP](https://playbooks.com/mcp/runekaagaard-alchemy)
287- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)
288 
289## Contributing
290 
291Contributions are warmly welcomed! Whether it's bug reports, feature requests, documentation improvements, or code contributions - all input is valuable. Feel free to:
292 
293- Open an issue to report bugs or suggest features
294- Submit pull requests with improvements
295- Enhance documentation or share your usage examples
296- Ask questions and share your experiences
297 
298The goal is to make database interaction with Claude even better, and your insights and contributions help achieve that.
299 
300## License
301 
302Mozilla Public License Version 2.0
303