Claude Desktop

Config file location

macOS
Windows

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

Minimal configuration

Add Isthmus to the mcpServers object:

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

Full configuration

Include optional settings for schema filtering, policy enrichment, and row limits:

{
  "mcpServers": {
    "isthmus": {
      "command": "isthmus",
      "args": ["--audit-log", "/tmp/isthmus-audit.ndjson"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb",
        "SCHEMAS": "public,analytics",
        "POLICY_FILE": "/path/to/policy.yaml",
        "MAX_ROWS": "500"
      }
    }
  }
}

Verify

Save the config file
Restart Claude Desktop (Cmd+Q, then reopen)
Look for the MCP tools icon in the chat input area
Ask: “What tables are in my database?”

Claude should call discover and return a summary of your database.

Troubleshooting

Binary not found

Claude Desktop needs isthmus in your PATH. Check where it’s installed:

which isthmus

If it’s not in your PATH, use the full path in the config. The location depends on how you installed:

Install script / prebuilt binary: /usr/local/bin/isthmus
go install: ~/go/bin/isthmus

"command": "/usr/local/bin/isthmus"

Wrong config file path

On macOS, the config file must be at exactly:

~/Library/Application Support/Claude/claude_desktop_config.json

Create the file if it doesn’t exist. Make sure it’s valid JSON.

Database unreachable

Test connectivity outside Claude Desktop first:

DATABASE_URL="postgres://user:password@localhost:5432/mydb" isthmus --dry-run

If this fails, check your connection string, network, and Postgres status.

Getting Started

Client Setup

Features

Security

Architecture

Config file location

Minimal configuration

Full configuration

Verify

Troubleshooting

​Config file location

​Minimal configuration

​Full configuration

​Verify

​Troubleshooting

Config file location

Minimal configuration

Full configuration

Verify

Troubleshooting