mcp-dbserver

自作の MCP サーバーで、AI エージェント — Claude Code、Claude Desktop、または MCP 互換のクライアント — に、PostgreSQL（pgvector 対応）、DynamoDB、MongoDB Atlas（Atlas Vector Search 対応）の3つのデータベースエンジンへの読み取り専用かつセキュリティスコープされたアクセスを一度に提供します。これは、マルチクラウドデータベースアーキテクチャの17年以上の経験を AI/エージェンティックツール領域へと広げた個人プロジェクトです。目標は「エージェントがデータベースにクエリできること」ではなく、本番参照アーキテクチャが要求するのと同じ最小権限・多層防御の規律を、サービスではなく LLM である呼び出し元に対して適用することを示すことです。

このリポジトリには、雇用先（現在または過去を問わず）のデータ、スキーマ、ビジネスロジックは一切含まれていません。掲載されているのは、このプロジェクト専用に生成された公開データまたは合成データのみです。

アーキテクチャ

flowchart LR
    Client["MCP client<br/>(Claude Code / Claude Desktop)"]

    subgraph Server["mcp-dbserver (stdio)"]
        direction TB
        Tools["Fixed tool surface<br/>(no generic 'run query' tool)"]
        Guard["guardrails.py + allowlist.py<br/>read-only + row-limit re-check"]
        Tools --> Guard
    end

    Client -- "MCP tool calls" --> Tools

    Guard --> PG[("PostgreSQL + pgvector<br/>RDS, IAM or password auth")]
    Guard --> DDB[("DynamoDB<br/>fixed table-target registry")]
    Guard --> Mongo[("MongoDB Atlas + Vector Search<br/>fixed collection-target registry")]

データベースへのすべての矢印は、名前付きで許可リスト登録された操作です — 生の SQL、生の MongoDB フィルター、生の DynamoDB キー条件が使われることは決してありません。完全な設計については ARCHITECTURE.md を参照してください。

Related MCP server: Secure RDS Read-Only MCP Server

セキュリティモデル

このプロジェクトが、典型的な「エージェントをデータベースに向ける」デモと差別化されている点です。詳細（ガードレールを設計するだけでなく実際にテストして見つかった2つの事項を含む）は ARCHITECTURE.md にあります。要約:

1. 読み取り専用、以上終わり。 v1 では、どのエンジンに対しても書き込み・更新・削除ツールは存在しません。書き込み可能なバージョンがもし存在することになれば、それは独自の脅威モデルを持つ別プロジェクトです。

2. テストによって見つかった、文書化された境界。 「書き込みツールなし」というガードレールは、エージェントが MCP プロトコル経由で できることを制約します。同じ認証情報に独立してアクセスできるコード実行可能なクライアント（チャット専用クライアントである Claude Desktop とは対照的に、Claude Code のようなクライアント）を制約することはできません。テストでは、Claude Code は削除ツールが存在しないことを正しく認識しました — その後、自作の psycopg スクリプトを書き、MCP サーバーを完全に迂回して削除を直接試みました。失敗したのは、設定されたデータベースロールに書き込み権限がなかったからにすぎません。つまり、コード実行可能なクライアントに対する真の最後の防衛線は、このコードに書き込みメソッドが存在しないことではなく、データベース/IAM レベルの読み取り専用ロールなのです。これは暗黙のままにするのではなく、明示的に文書化されています。

3. エージェントからの生クエリは禁止。 すべての操作は、型付きパラメータを持つ名前付きの許可リスト登録済みシェイプです — 固定の SQL テンプレート（Postgres）、固定のテーブル/コレクションターゲットレジストリと型付きキー（DynamoDB/MongoDB）— エージェント入力から構築されたフィルタードキュメント、キー条件式、SQL 文字列が使われることは決してありません。ベクトル検索ツールの初期ドラフトはテーブル/カラム名を直接引数として受け取るものでしたが、サーバーが実際のクライアントに接続される前に発見され修正されました（f-string 補間による実際の SQL インジェクション面）。

4. 実行時の多層防御。 許可リスト登録済みの Postgres クエリでさえ、実行前に guardrails.py によって再検証されます（SELECT/WITH 以外を拒否し、スタックされたステートメントを拒否し、要求内容に関係なく行数上限を強制します）。また、すべての接続はデータベースレベルで default_transaction_read_only = on を設定します。

5. 認証情報: 環境変数のみで、ログに記録されることもハードコードされることもありません。RDS IAM データベース認証がサポートされており、保存された Postgres パスワードよりも優先されます（rds:GenerateDBAuthToken による接続ごとの新しい約15分のトークン。長期有効な DB シークレットは一切ありません）。

サポート対象エンジンとツール

ツールごとの完全な説明と各ツールの背後にある理由は ARCHITECTURE.md にあります。semantic_search_documents と semantic_search_mongodb は同じデモデータセットと同じローカル埋め込みモデルに対して実行され、pgvector と Atlas Vector Search の結果を直接比較できるようにしています。

セットアップ

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # fill in your own, personal, non-work credentials

テストスイートを実行します（実データベースは不要です — ガードレール/許可リストのロジックは、3つのエンジンすべてについてフェイクに対してユニットテストされています）:

pytest

MCP サーバーを実行します（stdio トランスポート、Claude Code / Claude Desktop でのローカル使用向け）:

mcp-dbserver

ツールは、必須の環境変数が設定されているエンジンについてのみ登録されます — たとえば POSTGRES_DSN だけが設定されている場合、Postgres のツールのみが表示されます。エンジンごとのすべての変数については .env.example を参照してください。

Postgres デモデータセット

data/demo_documents.jsonl は、約30件の短いソフトウェア/インフラ解説スニペットからなる小さな合成データセットです（このプロジェクトのために書かれたもの）。これをロードし、埋め込みをローカルで生成します（fastembed の ONNX ランタイム — オフライン、外部 API キー不要、torch/torchvision への依存なし）:

python scripts/load_demo_dataset.py
python scripts/smoke_test_postgres.py      # connectivity + read-only guardrail
python scripts/verify_demo_dataset.py      # row count + semantic search sanity check

DynamoDB

テーブルは環境変数では設定されません — アクセス可能なテーブルは engines/dynamodb.py 内の固定レジストリ（_TABLE_TARGETS）から取得されます。*_dynamodb_* ツールを有効にするには、AWS_REGION を設定します（および、登録済みテーブルの ARN に対する dynamodb:GetItem/Scan/DescribeTable にスコープされた、環境変数/プロファイル/インスタンスロールによる標準的な AWS 認証情報）。

MongoDB Atlas デモデータセット

Postgres のセットアップを正確にミラーしています — 同じデータセット、同じ埋め込みモデル — そのため結果を直接比較できます。MONGODB_URI/MONGODB_DATABASE を設定し（組み込みの read ロールを持つ Atlas ユーザー。readWrite ではありません）、次に:

python scripts/load_demo_dataset_mongodb.py    # upserts data + creates the Atlas Vector Search index
python scripts/verify_demo_dataset_mongodb.py  # index builds asynchronously; re-run if search comes back empty

プロジェクト構成

src/mcp_dbserver/
  guardrails.py        # read-only + row-limit enforcement, engine-agnostic
  allowlist.py          # named, parameterized Postgres query registry
  config.py              # env-var credential loading, per engine
  engines/
    postgres.py           # allowlisted queries + pgvector semantic search
    dynamodb.py             # fixed table-target registry, get/scan/count
    mongodb.py                # fixed collection-target registry, get/list/count/$vectorSearch
  server.py             # MCP entrypoint, registers tools per configured engine
tests/                   # guardrail/allowlist/engine unit tests, all three engines (no live DB needed)
scripts/                 # demo dataset loaders/verifiers, Postgres smoke test

本番スケールで異なるアプローチを取る点

v1 が意図的に解決しないことを明示することは、本番で完成済みであるかのように装うことよりも多くのことを示します:

• クライアント ↔ サーバー認証。 v1 は stdio 上で動作し、クライアントによってサブプロセスとして直接起動されます — OS プロセス境界 が 信頼境界であり、これはローカルでの単一ユーザー使用には適していますが、それ以外には適しません。ネットワーク展開（HTTP/SSE、複数のクライアントから到達可能）では、デモ以外の何かになる前に、エンジンごとにスコープされたクライアント単位の API キーと、サーバーの前方での TLS 終端が必要です。

• 可観測性。 クエリロギングやメトリクスはまだありません。ネットワーク展開前には最低限: どの名前付きクエリ/操作が呼び出されたか、いつ、成功したかどうか — ログの中にデータの2番目のコピーを密かに作り出さないよう、パラメータ値や行の内容は意図的に決して記録しません。

• レート制限。 未実装です。単一のローカル stdio クライアント以外からサーバーに到達できるようになって初めて重要になりますが、負荷がかかってから気づくより、名前を挙げておく価値のあるギャップです。

• MySQL。 v1 のスコープ外と明示されています。追加される場合も、Postgres と同じ許可リスト + ガードレールのパターンに従います — 新しい設計は不要で、4番目のエンジン分の配管だけです。

• DynamoDB/MongoDB のフィルターシェイプの問題は、計画よりも複雑ではなく単純になりました。 元の設計では、DynamoDB/MongoDB の許可リスト登録済みフィルターごとに型付きスキーマが検討されていました。実際にリリースされたものはより小さく、固定のターゲットレジストリと、エンジンごとの固定された小さな名前付き操作のセットで、汎用の find(filter) や query(key_condition) ツールはまったくありません。言及する価値があるのは、検証 DSL を構築するという直感のほうが「印象的に聞こえる」選択肢であり、より単純な選択肢が同じギャップをより確実に埋めることが判明したからです — $where や任意のキー条件が潜り込める寛容なシェイプは存在しません。そのためのフィールドがないからです。