Isthmus

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

# 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 thequickstart guidefor step-by-step setup with Claude Desktop, Cursor, Windsurf, and more.

Images are published toDocker Hubon every release (linux/amd64 and linux/arm64).

docker run --rm \ -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/mydb" \ guillermosasso/isthmus

docker pull guillermosasso/isthmus:0.1.1

{ "mcpServers": { "isthmus": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "DATABASE_URL=postgres://user:pass@host.docker.internal:5432/mydb", "guillermosasso/isthmus" ] } } }

- 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 viapg_queryparser — onlySELECTandEXPLAINallowed (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)

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 asecurity 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. Thepolicy engineenriches 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.

Full reference:isthmus.dev/tools/overview

Visitisthmus.devfor 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

SeeCONTRIBUTING.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

Maritime intelligence for tracking vessels, analysing ports, and exploring ship data.