Isthmus

Isthmus

データベース向け MCP サーバー

ドキュメント · クイックスタート · インストール · 課題

---

Isthmus は、AI モデルに PostgreSQL データベースへの安全な読み取り専用アクセスを提供するローカル MCP サーバーです。バイナリは 1 つだけで、お使いのマシン上で動作し、認証情報が外部に送信されることはありません。

クイックスタート

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

Claude Desktop、Cursor、Windsurf などを使った手順ごとのセットアップについては、クイックスタートガイドをご覧ください。

Docker

イメージはリリースのたびに Docker Hub に公開されます（linux/amd64 および linux/arm64）。

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

特定のバージョンを指定する場合：

docker pull guillermosasso/isthmus:0.1.1

Claude Desktop で使うには、MCP の設定でコンテナを指定します：

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

機能

• スキーマの探索 — スキーマ、テーブル、カラム、外部キー、インデックスを調べられます（ドキュメント）
• 読み取り専用クエリ — サーバー側の行数制限とクエリタイムアウトを適用して SQL を実行します（ドキュメント）
• カラムのマスキング — カラムごとのマスク（置換、ハッシュ化、一部表示、NULL）で個人を特定できる情報を保護します。サーバー側で適用されます（ドキュメント）
• ポリシーエンジン — スキーマに業務上のコンテキストを追加し、AI がより適切な SQL を作成できるようにします（ドキュメント）
• SQL の検証 — pg_query パーサーによる AST レベルのホワイトリストを適用し、SELECT と EXPLAIN のみを許可します（ドキュメント）
• HTTP トランスポート — MCP を HTTP 経由で提供し、ウェブベースのクライアント、ChatGPT Desktop、リモートアクセスに対応します（ドキュメント）
• OpenTelemetry — クエリのパフォーマンスとエラー監視のための分散トレーシングとメトリクスに対応します（ドキュメント）
• あらゆる MCP クライアントに対応 — Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code、ChatGPT Desktop で利用できます（クライアントの設定）

仕組み

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 は AI クライアントとデータベースの間に位置します。すべてのリクエストはセキュリティパイプラインを通過します。PostgreSQL 独自のパーサーを使って AST レベルで SQL を検証し、サーバー側の行数制限とタイムアウトを設定した読み取り専用トランザクションでクエリを実行します。また、結果が AI に届く前に PII 列をマスキングします。ポリシーエンジンはスキーマのメタデータにビジネスコンテキストを追加し、AI がより適切な SQL を記述できるようにします。すべてのアクティビティは追記専用の監査ログに記録され、オプションで OpenTelemetry トレーシングも利用できます。

MCP ツール

ツール	機能
list_schemas	利用可能なデータベーススキーマを見つけます
list_tables	行数、サイズ、説明を含むテーブル情報を表示します
describe_table	列、型、キー、インデックス、統計情報を表示します
profile_table	サンプル行、ディスク使用量、推定されるリレーションシップを詳しく分析します
query	読み取り専用 SQL を実行し、結果を JSON で返します
explain_query	オプションの ANALYZE を含む PostgreSQL の実行計画を表示します

全リファレンス：isthmus.dev/tools/overview

ドキュメント

詳しいドキュメントは isthmus.dev をご覧ください。

• インストール — ビルド済みバイナリ、go install、Docker
• 設定 — 環境変数、CLI フラグ、完全なリファレンス
• クライアントのセットアップ — Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code
• 列のマスキング — redact、hash、partial、null による PII 保護
• ポリシーエンジン — ビジネスコンテキスト、スキーマのフィルタリング
• ツールリファレンス — 各ツールの機能と、AI による利用方法

コントリビュート

CONTRIBUTING.md をご覧ください。統合テストには Go 1.25+ と Docker が必要です。

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

ライセンス

Apache 2.0