How to add MCP Alchemy to Windsurf

Connect Claude directly to PostgreSQL, MySQL, SQLite, Oracle, MS SQL and other SQLAlchemy databases. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 410★ · stdio · no auth

Windsurf config for MCP Alchemy

uvx --from mcp-alchemy==2025.8.15.91819 --refresh-package mcp-alchemy mcp-alchemy

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

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the MCP Alchemy config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5MCP Alchemy's tools become available to Cascade.

Before you start

uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
A SQLAlchemy-compatible database and its driver (e.g. psycopg2-binary, pymysql, pymssql, oracledb)
A DB_URL connection string for the target database

What MCP Alchemy can do in Windsurf

all_table_names

Return all table names in the database as a comma-separated list. No input required.

filter_table_names

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

schema_definitions

Get detailed schema for specified tables. Input: table_names (string[]). Returns column names and types, primary keys, foreign key relationships, and nullable flags.

execute_query

Execute a SQL query with vertical output format. Inputs: query (string) and optional params (object). Features smart truncation of large results, clean NULL display, ISO formatted dates, and full result set access via claude-local-files.

Security

Connects to your databases using credentials embedded in the DB_URL connection string. Use a least-privilege database account, since the LLM can execute arbitrary SQL via the execute_query tool.

MCP Alchemy + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the MCP Alchemy config there under the "mcpServers" key and restart the client.

Is MCP Alchemy safe to use with Windsurf?

Connects to your databases using credentials embedded in the DB_URL connection string. Use a least-privilege database account, since the LLM can execute arbitrary SQL via the execute_query tool.

Which databases are supported?

PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, Vertica, and any other SQLAlchemy-compatible database. You add the appropriate driver in the --with parameter and set a matching DB_URL.

How do I handle result sets larger than Claude's context window?

Set the CLAUDE_LOCAL_FILES_PATH environment variable and configure claude-local-files. The integration activates automatically, giving access to complete result sets for deeper analysis and export.

Can I tune the database connection pool?

Yes. MCP Alchemy uses connection pooling optimized for long-running MCP servers (pool_pre_ping=True, pool_size=1, max_overflow=2, pool_recycle=3600, AUTOCOMMIT). You can override these via the DB_ENGINE_OPTIONS environment variable, which accepts a JSON string of SQLAlchemy engine options.

View repo Full MCP Alchemy page