MCP Alchemy for Claude Code: Setup & Config

What you can do with MCP Alchemy in Claude Code

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.
• Use the companion file integration for analysis that needs unabridged query results.

Before you start: MCP Alchemy in Claude Code

• 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 Code configuration

1. Choose Claude Code configuration scope

   For MCP Alchemy, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add MCP Alchemy to Claude Code

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

3. Check MCP Alchemy in Claude Code

   MCP Alchemy: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "mcp-alchemy": {
      "type": "stdio",
      "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>"
      }
    }
  }
}

claude mcp add-json --scope project 'mcp-alchemy' '{"type":"stdio","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 Code

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

schema_definitions

For MCP Alchemy's schema_definitions, review the permission request and arguments in Claude Code before approval.

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

filter_table_names

For MCP Alchemy's filter_table_names, review the permission request and arguments in Claude Code before approval.

all_table_names

For MCP Alchemy's all_table_names, review the permission request and arguments in Claude Code before approval.

execute_query

For MCP Alchemy's execute_query, review the permission request and arguments in Claude Code before approval.

Run SQL with optional parameter values and display rows in a vertical layout.

MCP Alchemy: full stored tool descriptions

Troubleshooting MCP Alchemy in Claude Code

• If MCP Alchemy fails to start, check uvx --from (from uv, for Python tools), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• MCP Alchemy: check CLAUDE_LOCAL_FILES_PATH, DB_ENGINE_OPTIONS, DB_URL, EXECUTE_QUERY_MAX_CHARS; keep credentials out of shared .mcp.json.
• MCP Alchemy uses stdio here: Claude Code 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 Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions