# runekaagaard/mcp-alchemy [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/runekaagaard/mcp-alchemy  
**GitHub Stars:** 419  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/runekaagaard-mcp-alchemy

## Description
Universal SQLAlchemy-based database integration supporting PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server and many more databases. Features schema and relationship inspection, and large dataset analysis capabilities.

## Tools
Capabilities this server exposes over MCP:

- **q**
- **table_names**
- **query**
- **params**

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-alchemy": {
    "command": "uvx",
    "args": ["--from","mcp-alchemy==2026.9.5.185701","--refresh-package","mcp-alchemy","mcp-alchemy"],
    "env": {
      "DB_URL": ""
    }
  }
}
```

**Requires environment variables:** `DB_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What runekaagaard/mcp-alchemy MCP server does

The runekaagaard/mcp-alchemy MCP server gives an MCP client access to a configured SQLAlchemy database. It is intended for database discovery and query-oriented analysis rather than application-specific business actions. An agent can find tables, inspect columns and relationships, and run SQL with optional parameters.

The README documents support for PostgreSQL, MySQL, MariaDB, SQLite, Oracle, Microsoft SQL Server, CrateDB, Vertica, and other databases with SQLAlchemy dialects. The actual database coverage depends on SQLAlchemy compatibility and the driver installed for the selected dialect.

## How it works

The server reads a database connection URL from DB_URL and creates a SQLAlchemy engine. Database-specific drivers are supplied separately when launching the server; the examples use psycopg2-binary for PostgreSQL, pymysql for MySQL and MariaDB, pymssql for Microsoft SQL Server, oracledb for Oracle, sqlalchemy-cratedb for CrateDB, and vertica-python for Vertica.

Its discovery flow can begin with a complete table listing or a substring filter. Schema inspection accepts selected table names and reports columns, types, primary keys, nullability, and foreign-key relationships. Query execution returns rows in a vertical, readable format, formats dates as ISO values, displays NULL explicitly, and truncates output according to a configurable character limit.

The server uses a connection pool aimed at long-running MCP processes. Its documented defaults include connection liveness checks, one persistent connection, limited overflow capacity, one-hour connection recycling, and autocommit isolation. These engine settings can be changed with a JSON object in DB_ENGINE_OPTIONS.

## Setup and configuration

Install uv, then launch the package with uvx or run the checked-out source with uv. A typical packaged configuration uses the `mcp-alchemy` package and ends with the `mcp-alchemy` executable. SQLite requires no additional driver in the documented example; other database types need the appropriate `--with` dependency.

Required configuration:

- `DB_URL`: a SQLAlchemy database URL, including credentials and dialect details where applicable.

Optional configuration includes `CLAUDE_LOCAL_FILES_PATH`, `EXECUTE_QUERY_MAX_CHARS`, and `DB_ENGINE_OPTIONS`. The output limit defaults to 4000 characters. `DB_ENGINE_OPTIONS` must contain JSON representing SQLAlchemy engine options.

## Tools and capabilities

The documented API provides these operations:

- List every table in the database.
- Filter table names using a search string.
- Retrieve detailed definitions for selected tables.
- Execute SQL with an optional parameter object.
- Work with complete query results through the separate claude-local-files integration when its path is configured.

With that integration enabled, the runekaagaard/mcp-alchemy MCP server can make full result sets available outside the normal response window for reports, visualizations, and further analysis. The README describes this as an optional companion configuration, not a built-in database export system.

## Limitations and notes

The server requires a valid SQLAlchemy connection URL and a compatible database driver. Credentials are typically part of that URL, so configuration should protect the resulting client settings. Large-query output is truncated unless the optional local-files workflow is configured. The README’s packaged examples pin version `2026.8.1.2602`; cached package metadata may briefly cause version errors after a release, in which case restarting the MCP client is recommended.

The listed tool names in the README API are `all_table_names`, `filter_table_names`, `schema_definitions`, and `execute_query`; these correspond to the table-listing, filtering, schema, and query functions exposed by the server. The runekaagaard/mcp-alchemy MCP server does not document write-specific tools or database migration features, so it should be evaluated primarily for inspection and SQL execution use cases.

_Full upstream README: https://allmcps.com/mcp/runekaagaard-mcp-alchemy/readme_