USQLMCP

usqlmcp

通用 SQL MCP（Model Context Protocol）。

功能

• 工具

  • read_query：执行 SELECT 查询并返回结果。
  • write_query：执行 INSERT、UPDATE、DELETE 或 ALTER 查询，并返回受影响的行数。
  • create_table：执行 CREATE TABLE 查询，在数据库中定义新表。
  • describe_table_schema：获取给定表的 JSON 架构，包括所有受支持数据库中的列名和数据类型。

• 资源

  • usqlmcp://<table>/schema：以 JSON 资源的形式访问数据库中任意表的架构。
  • 系统会自动发现并注册每个表各自的架构资源。

安装

usqlmcp 可通过[发布版本][]获取。

通过发布版本安装

1. 下载适用于你平台的发布版本
2. 从 .tar.bz2 或 .zip 文件中提取 usqlmcp 或 usqlcmp.exe 文件
3. 将提取出的可执行文件移动到 $PATH（Linux/macOS）或 %PATH%（Windows）中的某个位置

设置

在 Cursor 中集成 MCP

将以下配置添加到 ~/.cursor/mcp.json 文件中，或通过 Cursor 的设置菜单进行配置。

{
    "mcpServers": {
        "usqlmcp": {
            "command": "usqlmcp",
            "args": ["--dsn", "sqlite3:///your/db/dsn/file.db"]
        }
    }
}

其他工具

{
    "servers": {
        "usqlmcp": {
            "type": "stdio",
            "command": "usqlmcp",
            "args": ["--dsn", "sqlite3:///your/db/dsn/file.db"]
        }
    }
}

Docker 用法

你可以在 MCP JSON 配置中指定相应的命令和参数，从而将 usqlmcp 配置为在 Cursor 中通过 Docker 运行。

示例：Postgres（Docker）

将以下内容添加到 ~/.cursor/mcp.json：

{
    "mcpServers": {
        "usqlmcp": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "ghcr.io/thesoulless/usqlmcp:latest",
                "--dsn", "postgres://username:[email protected]:5432/dbname?sslmode=disable"
            ]
        }
    }
}

注意：连接主机上的数据库时，请使用 host.docker.internal，而不是 localhost 或 127.0.0.1。

示例：SQLite 与卷挂载（Docker）

若要使用本地计算机上的 SQLite 数据库文件，请将以下内容添加到 ~/.cursor/mcp.json：

{
    "mcpServers": {
        "usqlmcp": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-v", "/path/to/local/mydatabase.db:/data/mydatabase.db",
                "ghcr.io/thesoulless/usqlmcp:latest",
                "--dsn", "sqlite3:///data/mydatabase.db"
            ]
        }
    }
}

这会将本地 SQLite 数据库文件直接挂载到容器中，使容器仅能访问所需内容。

致谢

本项目依赖 usql，这是一个用于 SQL 数据库的通用命令行界面。