Skip to content
Back to search

mcp-alchemy

A MCP (model context protocol) server that gives the LLM access to and knowledge about relational databases like SQLite, Postgresql, MySQL & MariaDB, Oracle, and MS-SQL.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/runekaagaard--mcp-alchemy/badge.svg)](/listings/runekaagaard--mcp-alchemy)

HTML

<a href="/listings/runekaagaard--mcp-alchemy"><img src="/api/listings/runekaagaard--mcp-alchemy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Ensure you have uv installed:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 335 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.