{"id":23943939,"url":"https://github.com/runekaagaard/mcp-alchemy","last_synced_at":"2025-04-08T03:17:07.371Z","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":"2025-04-03T16:58:01.000Z","size":1484,"stargazers_count":117,"open_issues_count":1,"forks_count":22,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-03T17:34:52.807Z","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}},"created_at":"2024-12-26T14:09:30.000Z","updated_at":"2025-04-03T16:58:05.000Z","dependencies_parsed_at":"2025-01-25T10:20:14.077Z","dependency_job_id":"94c8978c-f692-4663-abda-2dc8572b28e7","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,"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","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767237,"owners_count":20992548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2025-04-08T03:17:07.365Z","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","Uncategorized","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データサイエンスツール","Uncategorized","AI Services","Databases"],"readme":"# MCP Alchemy\n\n**Status: Works great and is in daily use without any known bugs.**\n\n**Status 2: I'm currently working on publishing it to PYPI and finding the most userfriendly way to run it with uvx, so inspect installation instructions to change during the next couple of weeks.**\n\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 and a host of other [SQLAlchemy-compatible](https://docs.sqlalchemy.org/en/20/dialects/) databases.\n\n![MCP Alchemy in action](screenshot.png)\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## Usage with Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"my_database\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/mcp-alchemy\", \"run\", \"mcp_alchemy.py\"],\n      \"env\": {\n        \"DB_URL\": \"mysql+pymysql://root:secret@localhost/databasename\",\n      }\n    }\n  }\n}\n```\n\nEnvironment Variables:\n\n- `DB_URL`: SQLAlchemy [database URL](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls) (required)\n  Examples:\n  - PostgreSQL: `postgresql://user:password@localhost/dbname`\n  - MySQL: `mysql+pymysql://user:password@localhost/dbname`\n  - MariaDB: `mariadb+pymysql://user:password@localhost/dbname`\n  - SQLite: `sqlite:///path/to/database.db`\n- `CLAUDE_LOCAL_FILES_PATH`: Directory for full result sets (optional)\n- `EXECUTE_QUERY_MAX_CHARS`: Maximum output length (optional, default 4000)\n\n## Installation\n\n1. Clone repository:\n```bash\ngit clone https://github.com/runekaagaard/mcp-alchemy.git\n```\n\n2. Ensure you have uv\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n3. Add database to claude_desktop_config.json (see above)\n\n## Database Drivers\n\nThe following database drivers are included by default:\n- SQLite: Built into Python, no additional installation needed\n- MySQL/MariaDB: Via `pymysql`\n- PostgreSQL: Via `psycopg2-binary`\n\nTo use other databases supported by SQLAlchemy, install the appropriate driver:\n```bash\n# Microsoft SQL Server\nuv pip install pymssql\n\n# Oracle\nuv pip install cx_oracle\n\n# Other databases\n# See: https://docs.sqlalchemy.org/en/20/dialects/\n```\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## 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"}