MCP Alchemy for VS Code: Setup & Config

What you can do with MCP Alchemy in VS 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.
• Execute parameterized SQL through a Claude Desktop conversation.

Before you start: MCP Alchemy in VS 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 VS Code configuration

1. Choose VS Code configuration scope

   For MCP Alchemy, open Workspace: .vscode/mcp.json. Merge into servers; preserve existing inputs.

2. Add MCP Alchemy to VS Code

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

3. Check MCP Alchemy in VS Code

   MCP Alchemy: Start in VS Code’s MCP controls; inspect output and trust prompts.

{
  "servers": {
    "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 VS Code

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

schema_definitions

Look for schema_definitions among VS Code's agent-mode tools after starting MCP Alchemy through the MCP controls.

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

filter_table_names

Look for filter_table_names among VS Code's agent-mode tools after starting MCP Alchemy through the MCP controls.

all_table_names

Look for all_table_names among VS Code's agent-mode tools after starting MCP Alchemy through the MCP controls.

Return the connected database's table inventory without a filter.

execute_query

Look for execute_query among VS Code's agent-mode tools after starting MCP Alchemy through the MCP controls.

MCP Alchemy: full stored tool descriptions

Troubleshooting MCP Alchemy in VS Code

• Make uvx --from (from uv, for Python tools) available in the workspace, container, or remote environment hosting MCP Alchemy. Start through VS Code's MCP controls; inspect output and trust prompts.
• For MCP Alchemy, keep CLAUDE_LOCAL_FILES_PATH, DB_ENGINE_OPTIONS, DB_URL, EXECUTE_QUERY_MAX_CHARS out of version control; VS Code documents input variables and secret handling.
• MCP Alchemy uses stdio here: VS 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 VS Code troubleshooting lives in the /clients/vscode guide.

Frequently asked questions