Isthmus

Isthmus

数据库的 MCP 服务

文档 · 快速入门 · 安装 · 问题反馈

---

Isthmus 是一个本地 MCP 服务，可让 AI 模型安全地以只读方式访问你的 PostgreSQL 数据库。只需一个二进制文件，在你的计算机上运行，凭据绝不会离开本机。

快速入门

# 1. Install (pick one)
curl -fsSL https://isthmus.dev/install.sh | sh   # install script
docker pull guillermosasso/isthmus                # or Docker Hub

# 2. Add to your MCP client config (Claude Desktop example)

{
  "mcpServers": {
    "isthmus": {
      "command": "isthmus",
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

# 3. Ask your AI: "What tables are in my database?"

请参阅快速入门指南，了解如何逐步使用 Claude Desktop、Cursor、Windsurf 等进行设置。

Docker

每次发布时，都会将镜像发布到 Docker Hub（linux/amd64 和 linux/arm64）。

docker run --rm \
  -e DATABASE_URL="postgres://user:[email protected]:5432/mydb" \
  guillermosasso/isthmus

或者指定固定版本：

docker pull guillermosasso/isthmus:0.1.1

要与 Claude Desktop 配合使用，请将 MCP 配置指向容器：

{
  "mcpServers": {
    "isthmus": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "DATABASE_URL=postgres://user:[email protected]:5432/mydb",
        "guillermosasso/isthmus"
      ]
    }
  }
}

功能

• 架构发现 — 浏览架构、表、列、外键和索引（文档）
• 只读查询 — 执行 SQL，并应用服务端行数限制和查询超时（文档）
• 列掩码 — 使用逐列的遮盖、哈希、部分显示或置空掩码保护个人身份信息 (PII)，并由服务端强制执行（文档）
• 策略引擎 — 为架构补充业务上下文，让 AI 编写更好的 SQL（文档）
• SQL 验证 — 通过 pg_query 解析器在 AST 层进行白名单校验，仅允许 SELECT 和 EXPLAIN（文档）
• HTTP 传输 — 通过 HTTP 提供 MCP 服务，供 Web 客户端、ChatGPT Desktop 和远程访问使用（文档）
• OpenTelemetry — 提供分布式追踪和指标，用于查询性能与错误监控（文档）
• 兼容任何 MCP 客户端 — Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code、ChatGPT Desktop（客户端设置）

工作原理

flowchart TB
    Claude["Claude Desktop"] & Cursor["Cursor / VS Code"] -->|stdio| STDIO
    ChatGPT["ChatGPT / Web"] -->|HTTP| HTTP

    subgraph Transport["Transport"]
        STDIO["stdio"]
        HTTP["HTTP + Auth"]
    end

    STDIO & HTTP --> Router

    subgraph Tools["MCP Tools"]
        Router{{"router"}}
        Router --> Discover["discover"]
        Router --> Describe["describe_table"]
        Router --> Query["query"]
    end

    Discover & Describe --> Explorer

    subgraph Schema["Schema Explorer"]
        Explorer["Catalog Introspection"]
        Explorer --> Policy["Policy Engine"]
    end

    Query --> Validate

    subgraph Security["Security Pipeline"]
        direction TB
        Validate["AST Validation"] --> ReadOnly["Read-Only Tx"]
        ReadOnly --> RowLimit["Row Limit"]
        RowLimit --> Timeout["Timeout"]
    end

    Security --> PG[("PostgreSQL")]
    Schema --> PG

    PG --> Mask

    subgraph Post["Post-Processing"]
        direction TB
        Mask["PII Masking"] --> Sanitize["Error Sanitization"]
    end

    Post -.-> Audit["Audit Log"]
    Post -.-> OTel["OpenTelemetry"]
    Post --> Response["Safe Response"]
    Response --> Claude & Cursor & ChatGPT

    classDef client fill:#e8f4f8,stroke:#2196F3,color:#1565C0
    classDef transport fill:#fff3e0,stroke:#FF9800,color:#E65100
    classDef tools fill:#e8eaf6,stroke:#3F51B5,color:#283593
    classDef security fill:#fce4ec,stroke:#E53935,color:#b71c1c
    classDef explorer fill:#e8f5e9,stroke:#4CAF50,color:#1B5E20
    classDef postproc fill:#f3e5f5,stroke:#9C27B0,color:#4A148C
    classDef db fill:#fff8e1,stroke:#FFC107,color:#F57F17
    classDef obs fill:#eceff1,stroke:#607D8B,color:#37474F
    classDef response fill:#e0f2f1,stroke:#009688,color:#004D40

    class Claude,Cursor,ChatGPT client
    class STDIO,HTTP transport
    class Router,Discover,Describe,Query tools
    class Validate,ReadOnly,RowLimit,Timeout security
    class Explorer,Policy explorer
    class Mask,Sanitize postproc
    class PG db
    class Audit,OTel obs
    class Response response

Isthmus 位于 AI 客户端与数据库之间。每个请求都会经过安全管道——使用 PostgreSQL 自带的解析器在 AST 层面验证 SQL，查询在只读事务中运行，并设置服务端行数限制和超时；在结果到达 AI 之前，PII 列会经过遮蔽处理。策略引擎会为架构元数据补充业务上下文，让 AI 编写更好的 SQL。所有活动都会记录在仅追加的审计日志中，并可选择启用 OpenTelemetry 跟踪。

MCP 工具

工具	功能
list_schemas	发现可用的数据库架构
list_tables	查看表的行数、大小和描述
describe_table	查看列、类型、键、索引和统计信息
profile_table	深入分析：示例行、磁盘用量、推断出的关系
query	执行只读 SQL，并以 JSON 返回结果
explain_query	查看 PostgreSQL 执行计划，可选使用 ANALYZE

完整参考：isthmus.dev/tools/overview

文档

访问 isthmus.dev 查看完整文档：

• 安装 — 预构建二进制文件、go install、Docker
• 配置 — 环境变量、CLI 标志、完整参考
• 客户端设置 — Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code
• 列遮蔽 — 使用 redact、hash、partial、null 保护 PII
• 策略引擎 — 业务上下文、架构筛选
• 工具参考 — 各工具的功能及 AI 的使用方式

贡献

请参阅 CONTRIBUTING.md。集成测试需要 Go 1.25+ 和 Docker。

make build        # Build binary
make test         # All tests (needs Docker)
make test-short   # Unit tests only
make lint         # Lint

许可证

Apache 2.0