MCP Alchemy for Cursor: Setup & Config

What you can do with MCP Alchemy in Cursor

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

• Execute parameterized SQL through a Claude Desktop conversation.
• Use the companion file integration for analysis that needs unabridged query results.

Before you start: MCP Alchemy in Cursor

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

1. Choose Cursor configuration scope

   For MCP Alchemy, open Project: .cursor/mcp.json User: ~/.cursor/mcp.json. Merge into mcpServers at project or user scope.

2. Add MCP Alchemy to Cursor

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

3. Check MCP Alchemy in Cursor

   MCP Alchemy: Enable in Cursor’s MCP settings; inspect tools.

{
  "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 Cursor

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

schema_definitions

Find schema_definitions under MCP Alchemy in Cursor's MCP settings; inspect its arguments when the agent requests a call.

filter_table_names

Find filter_table_names under MCP Alchemy in Cursor's MCP settings; inspect its arguments when the agent requests a call.

all_table_names

Find all_table_names under MCP Alchemy in Cursor's MCP settings; inspect its arguments when the agent requests a call.

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

execute_query

Find execute_query under MCP Alchemy in Cursor's MCP settings; inspect its arguments when the agent requests a call.

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

MCP Alchemy: full stored tool descriptions

Troubleshooting MCP Alchemy in Cursor

• Cursor must find uvx --from (from uv, for Python tools) for MCP Alchemy. Enable the project/user entry in MCP settings and inspect its tools.
• Review CLAUDE_LOCAL_FILES_PATH, DB_ENGINE_OPTIONS, DB_URL, EXECUTE_QUERY_MAX_CHARS for MCP Alchemy before sharing project .cursor/mcp.json; project scope travels with the repository.
• MCP Alchemy uses stdio here: Cursor 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 Cursor troubleshooting lives in the /clients/cursor guide.

Frequently asked questions