Isthmus
A single binary MCP server that gives Claude, Cursor, and any MCP client safe, read-only access to your PostgreSQL database. Runs locally over stdio or HTTP — your credentials never leave your machine.
Overview
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: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_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)
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
Server Config
{
"mcpServers": {
"isthmus": {
"command": "isthmus",
"env": {
"DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
}
}
}
}Project Info
Created At
3 months agoUpdated At
3 months agoAuthor Name
guillermoBallesterStar
-Language
-License
-Tags
Recommend Servers
View AllMem Context
@turbyho
an hour ago
Sellerguide
11 hours ago
Sellerguide
11 hours ago
Project Memory
@kaaustubh
13 hours ago