Isthmus

Isthmus

The MCP server for your database

Docs · Quickstart · Install · Issues

---

Isthmus is a local MCP server that gives AI models safe, read-only access to your PostgreSQL database. One binary, runs on your machine, credentials never leave.

Quick start

# 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?"

See the quickstart guide for step-by-step setup with Claude Desktop, Cursor, Windsurf, and more.

Docker

Images are published to Docker Hub on every release (linux/amd64 and linux/arm64).

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

Or pin a specific version:

docker pull guillermosasso/isthmus:0.1.1

To use with Claude Desktop, point the MCP config at the container:

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

Features

• Schema discovery — explore schemas, tables, columns, foreign keys, and indexes (docs)
• Read-only queries — execute SQL with server-side row limits and query timeouts (docs)
• Column masking — protect PII with per-column redact, hash, partial, or null masks — enforced server-side (docs)
• Policy engine — enrich your schema with business context so the AI writes better SQL (docs)
• SQL validation — AST-level whitelist via pg_query parser — only SELECT and EXPLAIN allowed (docs)
• HTTP transport — serve MCP over HTTP for web-based clients, ChatGPT Desktop, and remote access (docs)
• OpenTelemetry — distributed tracing and metrics for query performance and error monitoring (docs)
• Works with any MCP client — Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code, ChatGPT Desktop (client setup)

How it works

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 sits between your AI client and your database. Every request flows through a security pipeline — SQL is validated at the AST level using PostgreSQL's own parser, queries run in read-only transactions with server-side row limits and timeouts, and PII columns are masked before results reach the AI. The policy engine enriches schema metadata with business context so the AI writes better SQL. All activity is recorded in an append-only audit log with optional OpenTelemetry tracing.

MCP tools

Tool	What it does
list_schemas	Discover available database schemas
list_tables	Tables with row counts, sizes, and descriptions
describe_table	Columns, types, keys, indexes, and statistics
profile_table	Deep analysis: sample rows, disk usage, inferred relationships
query	Execute read-only SQL, results as JSON
explain_query	PostgreSQL execution plans with optional ANALYZE

Full reference: isthmus.dev/tools/overview

Documentation

Visit isthmus.dev for the full documentation:

• Installation — prebuilt binaries, go install, Docker
• Configuration — env vars, CLI flags, full reference
• Client setup — Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code
• Column masking — PII protection with redact, hash, partial, null
• Policy engine — business context, schema filtering
• Tools reference — what each tool does and how the AI uses them

Contributing

See CONTRIBUTING.md. You'll need Go 1.25+ and Docker for integration tests.

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

License

Apache 2.0