home / mcp / mcp alchemy server

MCP Alchemy Server

A MCP (model context protocol) server that gives the LLM access to and knowledge about relational databases like SQLite, Postgresql, MySQL & MariaDB, Oracle, and MS-SQL.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "runekaagaard-mcp-alchemy": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-alchemy==2025.8.15.91819",
        "--refresh-package",
        "mcp-alchemy",
        "mcp-alchemy"
      ],
      "env": {
        "DB_URL": "sqlite:////absolute/path/to/database.db",
        "CLAUDE_LOCAL_FILES_PATH": "/path/to/local-files",
        "EXECUTE_QUERY_MAX_CHARS": "4000"
      }
    }
  }
}

MCP Alchemy lets Claude Desktop connect directly to your databases to explore structure, validate SQL, and generate artifacts from large datasets. It supports multiple database engines and uses a lightweight, persistent MCP server that runs alongside your database client for seamless querying and analysis.

How to use

You run an MCP server for each database you want Claude to interact with. Each server is started locally and communicates with Claude Desktop through MCP. You provide the database connection URL via the DB_URL environment variable, and you can tailor engine options or additional drivers with DB_ENGINE_OPTIONS or with specific driver packages. Use the appropriate configuration snippet below for your database, then start Claude Desktop and connect to the corresponding MCP server.

How to install

Prerequisites you need before starting: - Python and uv installed (uv manages MCP servers). If uv isn’t installed, install it using the installer script.

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

Connecting to your databases with MCP Alchemy

Choose the database you want to connect and copy the corresponding configuration snippet. Each snippet uses uvx to run the MCP server with the appropriate driver and a ready-to-use SQL URL in DB_URL. You can adjust the driver and options as needed. The following configurations assume Claude Desktop is set up to load MCP servers from your local environment.

{
  "mcpServers": {
    "my_sqlite_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "sqlite:////absolute/path/to/database.db"
      }
    }
  }
}

PostgreSQL

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

MySQL / MariaDB

{
  "mcpServers": {
    "my_mysql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "pymysql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mysql+pymysql://user:password@localhost/dbname"
      }
    }
  }
}

Microsoft SQL Server

{
  "mcpServers": {
    "my_mssql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "pymssql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mssql+pymssql://user:password@localhost/dbname"
      }
    }
  }
}

Oracle

{
  "mcpServers": {
    "my_oracle_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "oracledb",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "oracle+oracledb://user:password@localhost/dbname"
      }
    }
  }
}

CrateDB

{
  "mcpServers": {
    "my_cratedb": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "sqlalchemy-cratedb>=0.42.0.dev1",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "crate://user:password@localhost:4200/?schema=testdrive"
      }
    }
  }
}

Vertica

{
  "mcpServers": {
    "my_vertica_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.8.15.91819", "--with", "vertica-python",
               ""--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "vertica+vertica_python://user:password@localhost:5433/dbname",
        "DB_ENGINE_OPTIONS": "{\"connect_args\": {\"ssl\": false}}"
      }
    }
  }
}

Available tools

all_table_names

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

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 definitions including columns, keys, relationships, and nullable flags.

execute_query

Execute SQL query with vertical output format. Inputs: query (string), params (object, optional). Returns results in a secure vertical format with smart truncation and optional local-file access.