{"id":23943939,"url":"https://github.com/runekaagaard/mcp-alchemy","last_synced_at":"2026-08-28T00:46:55.313Z","repository":{"id":270019052,"uuid":"908616055","full_name":"runekaagaard/mcp-alchemy","owner":"runekaagaard","description":"A MCP (model context protocol) server that gives the LLM access to and knowledge about relational databases like SQLite, Postgresql, MySQL \u0026 MariaDB, Oracle, and MS-SQL.","archived":false,"fork":false,"pushed_at":"2026-07-31T22:26:13.000Z","size":1664,"stargazers_count":414,"open_issues_count":0,"forks_count":63,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-08-07T19:39:03.619Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runekaagaard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-26T14:09:30.000Z","updated_at":"2026-08-05T14:57:02.000Z","dependencies_parsed_at":"2025-01-25T10:20:14.077Z","dependency_job_id":"628d01f6-6024-4ed9-b174-7b26c60c9b46","html_url":"https://github.com/runekaagaard/mcp-alchemy","commit_stats":null,"previous_names":["runekaagaard/mcp-alchemy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/runekaagaard/mcp-alchemy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runekaagaard%2Fmcp-alchemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runekaagaard%2Fmcp-alchemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runekaagaard%2Fmcp-alchemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runekaagaard%2Fmcp-alchemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runekaagaard","download_url":"https://codeload.github.com/runekaagaard/mcp-alchemy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runekaagaard%2Fmcp-alchemy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36947905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-06T06:14:50.416Z","updated_at":"2026-08-28T00:46:55.306Z","avatar_url":"https://github.com/runekaagaard.png","language":"Python","funding_links":[],"categories":["Databases","Database \u0026 Messaging MCP Servers","サーバー実装","📚 Projects (1974 total)","MCP 服务器精选列表","Legend","🤖 AI/ML","MCP Servers","🗄️ Databases","Server Implementations","Contributing","Servers","Table of Contents"],"sub_categories":["Multi-Database Tools","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eデータベース","How to Submit","MCP Servers","🗄️ 数据库交互","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases","🗄️ Databases","🧮 \u003ca name=\"data-science-tools\"\u003e\u003c/a\u003eデータサイエンスツール","Data \u0026 Databases","AI Services"],"readme":"# MCP Alchemy\n\n\u003ca href=\"https://www.pulsemcp.com/servers/runekaagaard-alchemy\"\u003e\u003cimg src=\"https://www.pulsemcp.com/badge/top-pick/runekaagaard-alchemy\" width=\"400\" alt=\"PulseMCP Badge\"\u003e\u003c/a\u003e\n\n**Status: Works great and is in daily use without any known bugs.**\n\n**Status2: I just added the package to PyPI and updated the usage instructions. Please report any issues :)**\n\nLet Claude be your database expert! MCP Alchemy connects Claude Desktop directly to your databases, allowing it to:\n\n- Help you explore and understand your database structure\n- Assist in writing and validating SQL queries\n- Displays relationships between tables\n- Analyze large datasets and create reports\n- Claude Desktop Can analyse and create artifacts for very large datasets using [claude-local-files](https://github.com/runekaagaard/claude-local-files).\n\nWorks with PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, Vertica,\nand a host of other [SQLAlchemy-compatible](https://docs.sqlalchemy.org/en/20/dialects/) databases.\n\n![MCP Alchemy in action](https://raw.githubusercontent.com/runekaagaard/mcp-alchemy/refs/heads/main/screenshot.png)\n\n## Installation\n\nEnsure you have uv installed:\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n## Usage with Claude Desktop\n\nAdd to your `claude_desktop_config.json`. You need to add the appropriate database driver in the ``--with`` parameter.\n\n_Note: After a new version release there might be a period of up to 600 seconds while the cache clears locally \ncached causing uv to raise a versioning error. Restarting the MCP client once again solves the error._\n\n### SQLite (built into Python)\n```json\n{\n  \"mcpServers\": {\n    \"my_sqlite_db\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-alchemy==2026.8.1.2602\",\n               \"--refresh-package\", \"mcp-alchemy\", \"mcp-alchemy\"],\n      \"env\": {\n        \"DB_URL\": \"sqlite:////absolute/path/to/database.db\"\n      }\n    }\n  }\n}\n```\n\n### PostgreSQL\n```json\n{\n  \"mcpServers\": {\n    \"my_postgres_db\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-alchemy==2026.8.1.2602\", \"--with\", \"psycopg2-binary\",\n               \"--refresh-package\", \"mcp-alchemy\", \"mcp-alchemy\"],\n      \"env\": {\n        \"DB_URL\": \"postgresql://user:password@localhost/dbname\"\n      }\n    }\n  }\n}\n```\n\n### MySQL/MariaDB\n```json\n{\n  \"mcpServers\": {\n    \"my_mysql_db\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-alchemy==2026.8.1.2602\", \"--with\", \"pymysql\",\n               \"--refresh-package\", \"mcp-alchemy\", \"mcp-alchemy\"],\n      \"env\": {\n        \"DB_URL\": \"mysql+pymysql://user:password@localhost/dbname\"\n      }\n    }\n  }\n}\n```\n\n### Microsoft SQL Server\n```json\n{\n  \"mcpServers\": {\n    \"my_mssql_db\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-alchemy==2026.8.1.2602\", \"--with\", \"pymssql\",\n               \"--refresh-package\", \"mcp-alchemy\", \"mcp-alchemy\"],\n      \"env\": {\n        \"DB_URL\": \"mssql+pymssql://user:password@localhost/dbname\"\n      }\n    }\n  }\n}\n```\n\n### Oracle\n```json\n{\n  \"mcpServers\": {\n    \"my_oracle_db\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-alchemy==2026.8.1.2602\", \"--with\", \"oracledb\",\n               \"--refresh-package\", \"mcp-alchemy\", \"mcp-alchemy\"],\n      \"env\": {\n        \"DB_URL\": \"oracle+oracledb://user:password@localhost/dbname\"\n      }\n    }\n  }\n}\n```\n\n### CrateDB\n```json\n{\n  \"mcpServers\": {\n    \"my_cratedb\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-alchemy==2026.8.1.2602\", \"--with\", \"sqlalchemy-cratedb\u003e=0.42.0.dev1\",\n               \"--refresh-package\", \"mcp-alchemy\", \"mcp-alchemy\"],\n      \"env\": {\n        \"DB_URL\": \"crate://user:password@localhost:4200/?schema=testdrive\"\n      }\n    }\n  }\n}\n```\nFor connecting to CrateDB Cloud, use a URL like\n`crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true`.\n\n### Vertica\n```json\n{\n  \"mcpServers\": {\n    \"my_vertica_db\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"mcp-alchemy==2026.8.1.2602\", \"--with\", \"vertica-python\",\n               \"--refresh-package\", \"mcp-alchemy\", \"mcp-alchemy\"],\n      \"env\": {\n        \"DB_URL\": \"vertica+vertica_python://user:password@localhost:5433/dbname\",\n        \"DB_ENGINE_OPTIONS\": \"{\\\"connect_args\\\": {\\\"ssl\\\": false}}\"\n      }\n    }\n  }\n}\n```\n\n## Environment Variables\n\n- `DB_URL`: SQLAlchemy [database URL](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls) (required)\n- `CLAUDE_LOCAL_FILES_PATH`: Directory for full result sets (optional)\n- `EXECUTE_QUERY_MAX_CHARS`: Maximum output length (optional, default 4000)\n- `DB_ENGINE_OPTIONS`: JSON string containing additional SQLAlchemy engine options (optional)\n\n## Connection Pooling\n\nMCP Alchemy uses connection pooling optimized for long-running MCP servers. The default settings are:\n\n- `pool_pre_ping=True`: Tests connections before use to handle database timeouts and network issues\n- `pool_size=1`: Maintains 1 persistent connection (MCP servers typically handle one request at a time)\n- `max_overflow=2`: Allows up to 2 additional connections for burst capacity\n- `pool_recycle=3600`: Refreshes connections older than 1 hour (prevents timeout issues)\n- `isolation_level='AUTOCOMMIT'`: Ensures each query commits automatically\n\nThese defaults work well for most databases, but you can override them via `DB_ENGINE_OPTIONS`:\n\n```json\n{\n  \"DB_ENGINE_OPTIONS\": \"{\\\"pool_size\\\": 5, \\\"max_overflow\\\": 10, \\\"pool_recycle\\\": 1800}\"\n}\n```\n\nFor databases with aggressive timeout settings (like MySQL's 8-hour default), the combination of `pool_pre_ping` and `pool_recycle` ensures reliable connections.\n\n## API\n\n### Tools\n\n- **all_table_names**\n  - Return all table names in the database\n  - No input required\n  - Returns comma-separated list of tables\n  ```\n  users, orders, products, categories\n  ```\n\n- **filter_table_names**\n  - Find tables matching a substring\n  - Input: `q` (string)\n  - Returns matching table names\n  ```\n  Input: \"user\"\n  Returns: \"users, user_roles, user_permissions\"\n  ```\n\n- **schema_definitions**\n  - Get detailed schema for specified tables\n  - Input: `table_names` (string[])\n  - Returns table definitions including:\n    - Column names and types\n    - Primary keys\n    - Foreign key relationships\n    - Nullable flags\n  ```\n  users:\n      id: INTEGER, primary key, autoincrement\n      email: VARCHAR(255), nullable\n      created_at: DATETIME\n      \n      Relationships:\n        id -\u003e orders.user_id\n  ```\n\n- **execute_query**\n  - Execute SQL query with vertical output format\n  - Inputs:\n    - `query` (string): SQL query\n    - `params` (object, optional): Query parameters\n  - Returns results in clean vertical format:\n  ```\n  1. row\n  id: 123\n  name: John Doe\n  created_at: 2024-03-15T14:30:00\n  email: NULL\n\n  Result: 1 rows\n  ```\n  - Features:\n    - Smart truncation of large results\n    - Full result set access via [claude-local-files](https://github.com/runekaagaard/claude-local-files) integration\n    - Clean NULL value display\n    - ISO formatted dates\n    - Clear row separation\n\n## Claude Local Files\n\nWhen [claude-local-files](https://github.com/runekaagaard/claude-local-files) is configured:\n\n- Access complete result sets beyond Claude's context window\n- Generate detailed reports and visualizations\n- Perform deep analysis on large datasets\n- Export results for further processing\n\nThe integration automatically activates when `CLAUDE_LOCAL_FILES_PATH` is set.\n\n## Developing\n\nFirst clone the github repository, install the dependencies and your database driver(s) of choice:\n\n```\ngit clone git@github.com:runekaagaard/mcp-alchemy.git\ncd mcp-alchemy\nuv sync\nuv pip install psycopg2-binary\n```\n\nThen set this in claude_desktop_config.json:\n\n```\n...\n\"command\": \"uv\",\n\"args\": [\"run\", \"--directory\", \"/path/to/mcp-alchemy\", \"-m\", \"mcp_alchemy.server\", \"main\"],\n...\n```\n\n## My Other LLM Projects\n\n- **[MCP Redmine](https://github.com/runekaagaard/mcp-redmine)** - Let Claude Desktop manage your Redmine projects and issues.\n- **[MCP Notmuch Sendmail](https://github.com/runekaagaard/mcp-notmuch-sendmail)** - Email assistant for Claude Desktop using notmuch.\n- **[Diffpilot](https://github.com/runekaagaard/diffpilot)** - Multi-column git diff viewer with file grouping and tagging.\n- **[Claude Local Files](https://github.com/runekaagaard/claude-local-files)** - Access local files in Claude Desktop artifacts.\n\n## MCP Directory Listings\n\nMCP Alchemy is listed in the following MCP directory sites and repositories:\n\n- [PulseMCP](https://www.pulsemcp.com/servers/runekaagaard-alchemy)\n- [Glama](https://glama.ai/mcp/servers/@runekaagaard/mcp-alchemy)\n- [MCP.so](https://mcp.so/server/mcp-alchemy)\n- [MCP Archive](https://mcp-archive.com/server/mcp-alchemy)\n- [Playbooks MCP](https://playbooks.com/mcp/runekaagaard-alchemy)\n- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)\n\n## Contributing\n\nContributions are warmly welcomed! Whether it's bug reports, feature requests, documentation improvements, or code contributions - all input is valuable. Feel free to:\n\n- Open an issue to report bugs or suggest features\n- Submit pull requests with improvements\n- Enhance documentation or share your usage examples\n- Ask questions and share your experiences\n\nThe goal is to make database interaction with Claude even better, and your insights and contributions help achieve that.\n\n## License\n\nMozilla Public License Version 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunekaagaard%2Fmcp-alchemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunekaagaard%2Fmcp-alchemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunekaagaard%2Fmcp-alchemy/lists"}