Mcp Alchemy

什麼是 MCP-Alchemy？

MCP-Alchemy 是一個模型上下文協議（MCP）伺服器，旨在為大型語言模型（LLMs）提供訪問和了解各種關聯數據庫的能力。這包括流行的數據庫，如 SQLite、PostgreSQL、MySQL、MariaDB、Oracle 和 MS-SQL。通過利用 MCP-Alchemy，開發者可以增強他們的應用程序，使其能夠與這些數據庫無縫互動，實現更具動態性和數據驅動的功能。

MCP-Alchemy 的特點

• 多數據庫支持：MCP-Alchemy 支持多種關聯數據庫，允許靈活的集成和數據管理。
• 增強的 LLM 互動：它使 LLM 能夠從數據庫檢索和操作數據，讓它們更強大且具上下文感知能力。
• 開源：該項目公開可用，鼓勵全球開發者的合作和貢獻。
• 用戶友好的界面：MCP-Alchemy 設計時考慮了可用性，為開發者提供了簡單的界面以與數據庫互動。
• 強大的文檔：提供全面的文檔，以幫助用戶有效設置和使用伺服器。

如何使用 MCP-Alchemy

1. 安裝：首先從 GitHub 克隆 MCP-Alchemy 倉庫。使用以下命令：

   git clone https://github.com/runekaagaard/mcp-alchemy.git
   

2. 設置：按照文檔中的安裝說明，在本地機器或伺服器環境中設置伺服器。
3. 配置：通過根據您的數據庫憑據修改配置文件，配置伺服器以連接到所需的關聯數據庫。
4. 集成：通過使用提供的 API 端點發送查詢和接收響應，將 MCP-Alchemy 與您的 LLM 應用程序集成。
5. 測試：通過運行示例查詢來測試集成，以確保 LLM 能夠按預期訪問和操作數據。

常見問題解答

MCP-Alchemy 支持哪些數據庫？

MCP-Alchemy 支持多種關聯數據庫，包括 SQLite、PostgreSQL、MySQL、MariaDB、Oracle 和 MS-SQL。

MCP-Alchemy 是免費使用的嗎？

是的，MCP-Alchemy 是一個開源項目，根據 MPL-2.0 許可證免費使用。

我如何能為 MCP-Alchemy 做出貢獻？

您可以通過分叉倉庫、進行改進並提交拉取請求來貢獻。此外，您還可以通過 GitHub 問題頁報告問題或建議功能。

我可以在哪裡找到文檔？

文檔可在倉庫中找到，提供有關安裝、配置和使用的詳細說明。

MCP-Alchemy 可以在生產環境中使用嗎？

是的，MCP-Alchemy 設計上是穩健的，可以在生產環境中使用，前提是它經過適當配置和測試。

MCP Alchemy

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

Status: Works great and is in daily use without any known bugs.

Status2: I just added the package to PyPI and updated the usage instructions. Please report any issues :)

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, CrateDB, Vertica, and a host of other SQLAlchemy-compatible databases.

Installation

Ensure you have uv installed:

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

Usage with Claude Desktop

Add to your claude_desktop_config.json. You need to add the appropriate database driver in the --with parameter.

Note: After a new version release there might be a period of up to 600 seconds while the cache clears locally cached causing uv to raise a versioning error. Restarting the MCP client once again solves the error.

SQLite (built into Python)

{
  "mcpServers": {
    "my_sqlite_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "sqlite:////absolute/path/to/database.db"
      }
    }
  }
}

PostgreSQL

{
  "mcpServers": {
    "my_postgres_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "psycopg2-binary",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "postgresql://user:password@localhost/dbname"
      }
    }
  }
}

MySQL/MariaDB

{
  "mcpServers": {
    "my_mysql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "pymysql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mysql+pymysql://user:password@localhost/dbname"
      }
    }
  }
}

Microsoft SQL Server

{
  "mcpServers": {
    "my_mssql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "pymssql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mssql+pymssql://user:password@localhost/dbname"
      }
    }
  }
}

Oracle

{
  "mcpServers": {
    "my_oracle_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "oracledb",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "oracle+oracledb://user:password@localhost/dbname"
      }
    }
  }
}

CrateDB

{
  "mcpServers": {
    "my_cratedb": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "sqlalchemy-cratedb>=0.42.0.dev1",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "crate://user:password@localhost:4200/?schema=testdrive"
      }
    }
  }
}

For connecting to CrateDB Cloud, use a URL like crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true.

Vertica

{
  "mcpServers": {
    "my_vertica_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "vertica-python",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "vertica+vertica_python://user:password@localhost:5433/dbname",
        "DB_ENGINE_OPTIONS": "{\"connect_args\": {\"ssl\": false}}"
      }
    }
  }
}

Environment Variables

• DB_URL: SQLAlchemy database URL (required)
• CLAUDE_LOCAL_FILES_PATH: Directory for full result sets (optional)
• EXECUTE_QUERY_MAX_CHARS: Maximum output length (optional, default 4000)
• DB_ENGINE_OPTIONS: JSON string containing additional SQLAlchemy engine options (optional)

Connection Pooling

MCP Alchemy uses connection pooling optimized for long-running MCP servers. The default settings are:

• pool_pre_ping=True: Tests connections before use to handle database timeouts and network issues
• pool_size=1: Maintains 1 persistent connection (MCP servers typically handle one request at a time)
• max_overflow=2: Allows up to 2 additional connections for burst capacity
• pool_recycle=3600: Refreshes connections older than 1 hour (prevents timeout issues)
• isolation_level='AUTOCOMMIT': Ensures each query commits automatically

These defaults work well for most databases, but you can override them via DB_ENGINE_OPTIONS:

{
  "DB_ENGINE_OPTIONS": "{\"pool_size\": 5, \"max_overflow\": 10, \"pool_recycle\": 1800}"
}

For databases with aggressive timeout settings (like MySQL's 8-hour default), the combination of pool_pre_ping and pool_recycle ensures reliable connections.

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

  • Find tables matching a substring
  • Input: q (string)
  • Returns matching table names

  Input: "user"
  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

  • Execute SQL query with vertical output format
  • Inputs:
    • query (string): SQL query
    • params (object, optional): Query parameters
  • Returns results in clean vertical format:

  1. row
  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

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.

Developing

First clone the github repository, install the dependencies and your database driver(s) of choice:

git clone git@github.com:runekaagaard/mcp-alchemy.git
cd mcp-alchemy
uv sync
uv pip install psycopg2-binary

Then set this in claude_desktop_config.json:

...
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-alchemy", "-m", "mcp_alchemy.server", "main"],
...

My Other LLM Projects

• MCP Redmine - Let Claude Desktop manage your Redmine projects and issues.
• MCP Notmuch Sendmail - Email assistant for Claude Desktop using notmuch.
• Diffpilot - Multi-column git diff viewer with file grouping and tagging.
• Claude Local Files - Access local files in Claude Desktop artifacts.

MCP Directory Listings

MCP Alchemy is listed in the following MCP directory sites and repositories:

• PulseMCP
• Glama
• MCP.so
• MCP Archive
• Playbooks MCP
• Awesome MCP Servers

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