1. Home
  2. Servers
  3. Databases
  4. MCP Alchemy

Server profile

MCP Alchemy

MCP Alchemy lets Claude Desktop inspect SQL database structure and execute queries through SQLAlchemy. An optional companion integration exposes complete result sets when the normal response is shortened.

View repositoryInstall & configure

Server facts

MCP Alchemy

Project

Author
runekaagaard
Repository
github.com/runekaagaard/mcp-alchemy
License
MPL-2.0
Category
Databases

Tech

Runtime / language
pythonPython
Transports
stdio
Remote available
No
Authentication
Not specified

Activity

GitHub stars
420
Last commit
Data as of

Tags

  • Database Schema
  • Parameterized Sql
  • Python
  • Query Results
  • Sqlalchemy

Overview

MCP Alchemy separates the query response an assistant reads from the complete dataset a query may produce. Normal output has a configurable character ceiling, with a default of 4,000, and presents rows vertically with explicit NULL handling and ISO dates. For larger analysis, claude-local-files can provide full results outside the immediate response. Setting its directory variable activates that optional integration, supporting subsequent reporting, visualization, or export. It is a companion project rather than an automatic part of the basic server launch. Query calls also accept parameters, allowing values to be supplied separately from the SQL text.

Before executing SQL, an assistant can discover tables, narrow their names by substring, and inspect selected definitions. Definitions expose nullability, key relationships, types, and columns rather than just a list of names. Database connectivity comes through SQLAlchemy, covering SQLite as well as engines such as Vertica, CrateDB, Oracle, SQL Server, PostgreSQL, MariaDB, and MySQL. The README gives driver-specific uvx examples: SQLite relies on Python's built-in support, while other examples request an additional dependency. DB_URL identifies the connection, and JSON engine options can override defaults. Connection management includes checking before use, recycling older connections, and a small persistent pool with overflow capacity. Queries use autocommit by default, an important behavior when considering writes. The stated license is MPL-2.0, and the client setup is documented around Claude Desktop.

Install & configure

Requirements

  • uv installation providing uvx
  • A database reachable through the chosen SQLAlchemy URL
  • Driver dependency matching the database if not using the SQLite example
Documented launch / install command
uvx --from mcp-alchemy==2025.8.15.91819 --refresh-package mcp-alchemy mcp-alchemy

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.

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Desktop configuration
{
  "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>"
      }
    }
  }
}

Read the Claude Desktop setup guide

Config file · Project: .cursor/mcp.json

User: ~/.cursor/mcp.json

The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.

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

Read the Cursor setup guide

Config file · Workspace: .vscode/mcp.json

For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.

VS Code configuration
{
  "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>"
      }
    }
  }
}

Read the VS Code setup guide

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.

Windsurf configuration
{
  "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>"
      }
    }
  }
}

Read the Windsurf setup guide

Config file · Project scope: .mcp.json at the repository root

The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Code configuration
{
  "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>"
      }
    }
  }
}

Read the Claude Code setup guide

Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.

Tools

Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.

ToolWhat it does
schema_definitionsInspect selected tables for column types, keys, relationships, and nullable fields.
filter_table_namesNarrow the table inventory to names containing the requested text.
all_table_namesReturn the connected database's table inventory without a filter.
execute_queryRun SQL with optional parameter values and display rows in a vertical layout.

Names, permissions, and defaults can change. Check the current upstream documentation before granting access.

Use cases

  • Inspect selected table definitions and relationships before drafting a query.
  • Narrow a large table inventory using a name substring.
  • Execute parameterized SQL through a Claude Desktop conversation.
  • Use the companion file integration for analysis that needs unabridged query results.

Strengths

  • Builds database access on SQLAlchemy with multiple documented driver configurations.
  • Connects table discovery to detailed schema inspection rather than query execution alone.
  • Can preserve full datasets separately from shortened assistant-facing output.
  • Exposes engine options for tuning connections and pooling behavior.

Limitations

  • The database-specific examples generally need an additional driver beyond the SQLite setup.
  • An ordinary query response is shortened once it reaches the configured character ceiling.
  • Default autocommit means queries are committed automatically rather than awaiting a later commit.

Frequently asked questions

The schema tool reports columns and types together with primary keys, foreign-key relationships, and whether fields are nullable.

The normal response is limited, but configured claude-local-files integration makes the complete result set available for further work. That integration is optional.

It reproduces the SQLite example, which uses support included in Python. Other database examples add the appropriate driver through --with.

Yes. DB_ENGINE_OPTIONS accepts JSON engine settings, including overrides for the documented connection-pool defaults. The default isolation mode is AUTOCOMMIT.

Both the structured metadata and the README identify version 2.0 of the Mozilla Public License.

Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.

Related MCP servers

MongoDB MCP Server

Databases

MongoDB MCP Server connects AI clients to MongoDB databases and Atlas. Its tools cover queries, schema inspection, database changes, and MongoDB knowledge searches, with read-only launch examples for safer exploration.

nodestdio1,143 GitHub stars

Neon MCP Server

Databases

Manage Neon Postgres projects, branches, queries, and migrations through an AI assistant. The hosted MCP service supports OAuth or API keys, read-only access, and project-level scoping.

nodestdio652 GitHub stars

MCP Toolbox for Databases

Databases

MCP Toolbox for Databases connects agents and IDEs to enterprise data through prebuilt tools or custom query definitions. It combines database access with connection pooling, authentication integration, and observability.

gostdio16,669 GitHub stars

MCP Server for MySQL

Databases

MCP Server for MySQL lets Claude and other AI clients inspect schemas and execute SQL. It defaults to read-only access, with optional write flags, SSH tunneling, multi-database support, and result redaction.

nodestdio2,166 GitHub stars

DBHub

Databases

DBHub exposes SQL execution and database discovery through a small MCP interface. It spans five database engines, supports multiple configured connections, and includes a web workbench for use without an assistant.

nodestdio3,664 GitHub stars

Supabase MCP Server

Databases

Connect AI assistants to Supabase projects for SQL, schema changes, debugging, and Edge Functions. Hosted HTTP setup supports project scoping, read-only access, and selectable feature groups.

nodestdio2,955 GitHub stars

Postgres MCP Pro

Databases

Give assistants PostgreSQL schema access, SQL execution, health checks, and performance analysis. Postgres MCP Pro adds query plans and hypothetical index evaluation with configurable read-only operation.

pythonstdio3,403 GitHub stars

MySQL MCP Server

Databases

Expose MySQL schema inspection, data samples, and SQL execution to MCP assistants. It supports multi-database access, optional SSH tunnels, and local or network deployment, with database permissions controlling available operations.

pythonstdio1,399 GitHub stars