使用说明

SQLAlchemy MCP服务器和CLI

一主控程序通过以下方式提供SQL数据库访问的服务器 SQLAlchemy.内置 FastMCP，它支持SQLAlchemy支持和操作的任何数据库只读或 可读写的 模式。

动机

随着人工智能代理在开发工作流程中变得越来越普遍，数据库访问出现了一个意想不到的问题：SQL很冗长。

当代理需要与数据库交互时，它通常必须生成完整的SQL查询，这会增加：

提示大小
令牌使用量
跨方言语法错误的可能性

此工具在SQLAlchemy上提供了一个MCP服务器和一个紧凑的CLI抽象，允许代理（或人类）使用短命令而不是完整的SQL语句与多个数据库进行交互。

优点：

不同数据库引擎的统一接口
SQLAlchemy处理方言差异
AI驱动的工作流程的命令明显更短

特性

通用数据库支持 --SQLite、PostgreSQL、MySQL、Oracle、MSSQL和 60+其他数据库通过SQLAlchemy
只读和读写模式 --使用命令行标志控制访问
MCP工具 --查询、反思和修改数据库
MCP资源 --浏览数据库模式、表、DDL和示例数据
MCP提示 --获取编写、解释和优化SQL查询的帮助

安装

pip install sqlalchemy-mcp-server

使用特定于数据库的驱动程序：

pip install "sqlalchemy-mcp-server[postgresql]"   # PostgreSQL (psycopg2)
pip install "sqlalchemy-mcp-server[mysql]"         # MySQL (PyMySQL)
pip install "sqlalchemy-mcp-server[oracle]"        # Oracle (oracledb)
pip install "sqlalchemy-mcp-server[mssql]"         # MSSQL (pyodbc)
pip install "sqlalchemy-mcp-server[all]"           # All drivers

从本地签出安装

如果您更愿意克隆存储库并从源代码安装（例如，运行未发布的版本或进行自己的更改）：

git clone https://github.com/alexxonline/sql-alchemy-mcp.git
cd sql-alchemy-mcp

# (recommended) create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# install the package from the current directory
pip install .

# ...or with database-specific drivers
pip install ".[postgresql]"      # or [mysql], [oracle], [mssql], [all]

# ...or as an editable install, so code changes take effect without reinstalling
pip install -e .

一旦以这种方式安装 sqlalchemy-mcp-server 命令的可用性与PyPI安装完全相同（请参见快速开始在......下面

从源代码运行，无需安装

您还可以直接从克隆的存储库运行，而无需安装软件包。安装依赖项后(pip install fastmcp sqlalchemy，加上您需要的任何驱动程序），从repo根目录将其作为模块调用：

python -m sqlalchemy_mcp_server --db-url "sqlite:///mydb.db"

python -m sqlalchemy_mcp_server ... 接受与 sqlalchemy-mcp-server 本README中显示的命令，包括 --cli 模式。

随着紫外线，您可以从结账处运行，而无需自己管理虚拟环境：

uv run sqlalchemy-mcp-server --db-url "sqlite:///mydb.db"

将MCP客户端指向本地签出时，使用模块表单作为命令：

{
  "mcpServers": {
    "my-database": {
      "command": "python",
      "args": [
        "-m", "sqlalchemy_mcp_server",
        "--db-url", "sqlite:///path/to/mydb.db",
        "--mode", "readonly"
      ],
      "cwd": "/path/to/sql-alchemy-mcp"
    }
  }
}

快速开始

# Read-only access to a SQLite database
sqlalchemy-mcp-server --db-url "sqlite:///mydb.db"

# Read-write access to PostgreSQL
sqlalchemy-mcp-server --db-url "postgresql://user:pass@localhost/mydb" --mode readwrite

# HTTP transport on a custom port
sqlalchemy-mcp-server --db-url "sqlite:///mydb.db" --transport http --port 9000

服务器选项

sqlalchemy-mcp-server [OPTIONS]

参数	默认值	描述
`--db-url`	（必填）	SQLAlchemy连接URL（或 `SQLALCHEMY_MCP_DB_URL` ）。
`--mode`	`readonly`	`readonly` 或 `readwrite`
`--transport`	`stdio`	MCP传输： `stdio` 或 `http`
`--port`	`8000`	HTTP传输端口
`--pool-size`	`5`	连接池大小
`--no-pool-pre-ping`	（关闭）	禁用连接预ping
`--cli`	（关闭）	在CLI模式下运行（执行一次命令，然后退出）

命令行接口命令模式

加 --cli 将任何工具、资源或提示作为一次性命令运行。程序连接、执行、将结果打印到stdout并退出——没有启动MCP服务器。

运行工具

# Query a table
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli query --sql "SELECT * FROM users"

# List tables
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli list_tables

# Describe a table
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli describe_table --table-name users

# Get CREATE TABLE DDL
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli get_table_ddl --table-name users

# Execute a write statement (requires --mode readwrite)
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --mode readwrite --cli execute \
  --sql "INSERT INTO users (name, email) VALUES ('alice', 'alice@example.com')"

# Create a table (requires --mode readwrite)
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --mode readwrite --cli create_table \
  --table-name events \
  --columns '[{"name": "id", "type": "INTEGER", "primary_key": true}, {"name": "title", "type": "TEXT"}]'

阅读资源

# Database overview
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli resource schema

# List all tables
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli resource tables

# Table details
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli resource table --table-name users

# Table DDL
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli resource table-ddl --table-name users

# Sample rows
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli resource table-sample --table-name users --limit 10

渲染提示

# Schema overview prompt
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli prompt explain_schema

# SQL query help
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli prompt sql_query \
  --table-names "users,orders" --task "find users with no orders"

# Query optimization
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli prompt optimize_query \
  --sql "SELECT * FROM users WHERE name = 'alice'"

输出格式化

# Pretty-printed JSON (default)
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli query --sql "SELECT * FROM users"

# Compact JSON (for piping)
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli query --sql "SELECT * FROM users" --compact

# Plain text table
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli query --sql "SELECT * FROM users" --format table

输出到stdout，错误到stderr，因此CLI模式可以与shell管道组合：

# Pipe to jq
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli query \
  --sql "SELECT * FROM users" --compact | jq '.[].name'

# Use in a script
TABLES=$(sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli list_tables --compact)

获得帮助

# List all CLI commands
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli --help

# Help for a specific command
sqlalchemy-mcp-server --db-url sqlite:///mydb.db --cli query --help

支持的数据库

数据库	驱动程序包	URL格式	安装额外
SQLite	（内置）	`sqlite:///path/to/db.db`	（无）
PostgreSQL	psycopg2二进制	`postgresql://user:pass@host/dbname`	`[postgresql]`
MySQL	PyMySQL	`mysql+pymysql://user:pass@host/dbname`	`[mysql]`
Oracle	oracledb	`oracle+oracledb://user:pass@host:1521/?service_name=svc`	`[oracle]`
MSSQL	pyodbc	`mssql+pyodbc://user:pass@dsn`	`[mssql]`
任何其他	（用户安装）	按 SQLAlchemy文档	手册

MCP客户端配置

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "my-database": {
      "command": "sqlalchemy-mcp-server",
      "args": [
        "--db-url", "sqlite:///path/to/mydb.db",
        "--mode", "readonly"
      ]
    }
  }
}

带uvx的Claude桌面（无需安装）

{
  "mcpServers": {
    "my-database": {
      "command": "uvx",
      "args": [
        "sqlalchemy-mcp-server",
        "--db-url", "postgresql://user:pass@localhost/mydb",
        "--mode", "readwrite"
      ]
    }
  }
}

可用工具

只读工具（始终可用）

工具	说明
`query`	执行只读SQL查询（SELECT/WITH/EXPLAIN）
`list_tables`	列出所有表和视图
`describe_table`	获取表的列、PK、FK和索引
`list_schemas`	列出所有数据库架构
`get_table_ddl`	获取表的CREATE TABLE DDL
`explain_query`	获取SELECT查询的执行计划

写入工具（仅限读写模式）

工具	说明
`execute`	执行SQL语句（INSERT、UPDATE、DELETE等）
`execute_many`	执行具有多个参数集的语句
`create_table`	根据列定义创建表
`drop_table`	放下一张桌子
`add_column`	向现有表添加列
`create_index`	创建索引（常规或唯一）

可用资源

URI	描述
`db://schema`	数据库概述（方言、模式、表计数）
`db://tables`	所有表和视图的列表
`db://tables/{table_name}`	特定表的详细架构
`db://tables/{table_name}/ddl`	CREATE TABLE DDL语句
`db://tables/{table_name}/sample`	表中的示例行

可用提示

提示	描述
`sql_query`	帮助为指定的表和任务编写SQL查询
`explain_schema`	数据库模式的全面概述
`optimize_query`	使用EXPLAIN输出分析和优化SQL查询

发展

# Clone and install in development mode
git clone https://github.com/alexxonline/sql-alchemy-mcp.git
cd sql-alchemy-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v