Isthmus

Isthmus

The MCP server for your database

👁 CI
👁 Go Report Card
👁 Latest Release
👁 GitHub Stars
👁 Go
👁 Docker

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.

👁 Isthmus demo

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:pass@host.docker.internal: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:pass@host.docker.internal: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

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