SQLAlchemy Database Access MCP Server

DatabasesPython

Connect Claude to relational databases for querying and schema exploration

Available Tools

all_table_names

Return all table names in the database as a comma-separated list

filter_table_names

Find tables matching a substring

q

schema_definitions

Get detailed schema for specified tables including column names, types, primary keys, foreign key relationships, and nullable flags

table_names

execute_query

Execute SQL query with vertical output format, with smart truncation of large results and integration with claude-local-files for full result sets

queryparams

SQLAlchemy Database Access provides a seamless connection between Claude and your relational databases, allowing the AI to explore database structures, write and validate SQL queries, and analyze datasets. It supports multiple database systems including PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, and other SQLAlchemy-compatible databases. With this tool, Claude becomes your database expert, helping you understand table relationships, generate reports, and work with large datasets. The integration with claude-local-files enables analysis of result sets that exceed Claude's context window, making it possible to work with extensive data collections efficiently.

Installation and Setup

SQLAlchemy Database Access can be easily installed and configured to work with Claude Desktop.

Prerequisites

Make sure you have uv installed on your system:

curl -LsSf https://astral.sh/uv/install.sh | sh

Configuration

Add the appropriate configuration to your claude_desktop_config.json file. The configuration varies slightly depending on which database system you're connecting to, as you'll need to include the appropriate database driver.

The basic configuration pattern is:

{
  "mcpServers": {
    "my_database": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.5.2.210242", 
               "--with", "DATABASE_DRIVER",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "DATABASE_CONNECTION_STRING"
      }
    }
  }
}

Replace DATABASE_DRIVER with the appropriate driver for your database system, and DATABASE_CONNECTION_STRING with your specific connection details.

Database-Specific Configurations

SQLite

{
  "mcpServers": {
    "my_sqlite_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2025.5.2.210242",
               "--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.5.2.210242", "--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.5.2.210242", "--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.5.2.210242", "--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.5.2.210242", "--with", "cx_oracle",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "oracle+cx_oracle://user:password@localhost/dbname"
      }
    }
  }
}

Additional Configuration Options

You can customize the behavior using these environment variables:

DB_URL: SQLAlchemy database URL (required)
CLAUDE_LOCAL_FILES_PATH: Directory for storing full result sets (optional)
EXECUTE_QUERY_MAX_CHARS: Maximum output length (optional, default 4000)

Claude Local Files Integration

For working with large datasets, you can integrate with claude-local-files by setting the CLAUDE_LOCAL_FILES_PATH environment variable. This allows Claude to:

Access complete result sets beyond Claude's context window
Generate detailed reports and visualizations
Perform deep analysis on large datasets
Export results for further processing

Usage

Once configured, you can interact with your database through Claude by using the available tools. Here are some examples of how to use them:

Exploring your database structure: Ask Claude to show you all tables in the database or filter tables by name.
Understanding table schemas: Request detailed schema information for specific tables to see columns, types, and relationships.
Executing SQL queries: Ask Claude to run SQL queries against your database and analyze the results.
Working with large datasets: When the claude-local-files integration is enabled, you can work with large result sets that exceed Claude's context window.

The tool presents results in a clean, readable format with proper handling of NULL values, date formatting, and row separation.