1. Home
  2. MCP Alchemy
  3. MCP Alchemy for Claude Desktop: Setup & Config

Data as of

MCP Alchemy for Claude Desktop: Setup & Config

Claude Desktop: MCP Alchemy lets Claude Desktop inspect SQL database structure and execute queries through SQLAlchemy.

What you can do with MCP Alchemy in Claude Desktop

Combine schema exploration with SQL execution and an optional path to full, unabridged result sets.

  • Inspect selected table definitions and relationships before drafting a query.
  • Narrow a large table inventory using a name substring.

Before you start: MCP Alchemy in Claude Desktop

  • uv installation providing uvx
  • A database reachable through the chosen SQLAlchemy URL
  • Driver dependency matching the database if not using the SQLite example

The version pin and argument sequence reproduce the SQLite README example. For another engine, use its documented --with dependency and matching DB_URL. The remaining environment entries are optional settings listed in the README; the full-result path is meaningful with claude-local-files configured.

MCP Alchemy Claude Desktop configuration

  1. Choose Claude Desktop configuration scope

    For MCP Alchemy, open macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json. Merge under mcpServers via Settings → Developer → Edit Config when available.

  2. Add MCP Alchemy to Claude Desktop

    Use the mcp-alchemy entry below in mcpServers. Keep MCP Alchemy's documented stdio connection fields and your other Claude Desktop entries.

  3. Check MCP Alchemy in Claude Desktop

    MCP Alchemy: Fully quit and reopen Claude Desktop; check developer diagnostics.

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

JSON
{
  "mcpServers": {
    "mcp-alchemy": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-alchemy==2025.8.15.91819",
        "--refresh-package",
        "mcp-alchemy",
        "mcp-alchemy"
      ],
      "env": {
        "DB_URL": "<required SQLAlchemy connection URL; use SQLite for this driver-free example>",
        "CLAUDE_LOCAL_FILES_PATH": "<optional directory used by the full-result companion integration>",
        "EXECUTE_QUERY_MAX_CHARS": "<optional character ceiling for query responses>",
        "DB_ENGINE_OPTIONS": "<optional engine overrides encoded as a JSON string>"
      }
    }
  }
}

MCP Alchemy tools available to Claude Desktop

MCP Alchemy's stored tool list documents 4 tools; compare it with Claude Desktop's connected tool list, because the stored list is not a live check.

schema_definitions

When Claude Desktop requests schema_definitions from MCP Alchemy, review the action before approving it.

Inspect selected tables for column types, keys, relationships, and nullable fields.

filter_table_names

When Claude Desktop requests filter_table_names from MCP Alchemy, review the action before approving it.

Narrow the table inventory to names containing the requested text.

all_table_names

When Claude Desktop requests all_table_names from MCP Alchemy, review the action before approving it.

execute_query

When Claude Desktop requests execute_query from MCP Alchemy, review the action before approving it.

MCP Alchemy: full stored tool descriptions

Troubleshooting MCP Alchemy in Claude Desktop

  • Fully quit and reopen Claude Desktop for MCP Alchemy. If uvx --from (from uv, for Python tools) is missing, check the desktop process's PATH, which may differ from your terminal.
  • In Claude Desktop's MCP Alchemy entry, check CLAUDE_LOCAL_FILES_PATH, DB_ENGINE_OPTIONS, DB_URL, EXECUTE_QUERY_MAX_CHARS. Keep secrets out of shared screenshots and repositories.
  • MCP Alchemy uses stdio here: Claude Desktop must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
  • Known limitation: The database-specific examples generally need an additional driver beyond the SQLite setup.
  • Known limitation: An ordinary query response is shortened once it reaches the configured character ceiling.
  • Known limitation: Default autocommit means queries are committed automatically rather than awaiting a later commit.
  • General Claude Desktop troubleshooting lives in the /clients/claude-desktop guide.

MCP Alchemy — details. Claude Desktop guide

Frequently asked questions

Claude Desktop loads MCP Alchemy from claude_desktop_config.json: ~/Library/Application Support/Claude/ on macOS, or %APPDATA%\Claude\ on Windows. Open it via Settings → Developer → Edit Config when available.

Claude Desktop's mcp-alchemy example uses stdio.

MCP Alchemy's Claude Desktop configuration invokes uvx --from (from uv, for Python tools).

Claude Desktop's MCP Alchemy example references CLAUDE_LOCAL_FILES_PATH, DB_ENGINE_OPTIONS, DB_URL, EXECUTE_QUERY_MAX_CHARS. Check these names if startup or authentication fails; the example alone does not distinguish required from optional values.

MCP Alchemy's stored list contains 4 tools, including schema_definitions, filter_table_names, all_table_names. Compare those names with Claude Desktop's connected tool list; the stored list is not a live check.

The schema tool reports columns and types together with primary keys, foreign-key relationships, and whether fields are nullable.

The normal response is limited, but configured claude-local-files integration makes the complete result set available for further work. That integration is optional.

It reproduces the SQLite example, which uses support included in Python. Other database examples add the appropriate driver through --with.