Secure Schema MCP

Secure Schema MCP

行データを公開することなく、AI コーディングツールにデータベース構造を提供する読み取り専用の MCP サーバーです。テーブル名とビュー名、列、型、キー、リレーションシップを、LLM のトークン使用量を抑えるよう設計されたコンパクトな形式で返します。

公開する情報

公開する情報	公開しない情報
テーブル名とビュー名	行の値やクエリ結果
列名と SQL の型	行数やサンプル
主キーと一意キー	データベースの認証情報
外部キーのリレーションシップ	書き込みツールやクエリツール

スキーマのメタデータも機密情報である可能性があります。たとえば、値を公開しなくても、ssn のような列名から情報が明らかになることがあります。そのため、本番環境では必ずテーブルの許可リストと専用のデータベースアカウントを使用してください。

要件

• Cursor や Codex などの MCP 対応クライアント
• 接続可能な SQLite、PostgreSQL、または MySQL データベース
• uvx を使わずにインストールする場合は Python 3.12 以降

SQLite のサポートには Python の組み込みドライバーを使用します。PostgreSQL と MySQL のドライバーは同梱されています。その他の SQLAlchemy ダイアレクトは、v1 ではテストも同梱もされていません。

IDE の設定

推奨されるセットアップでは、uvx を使用して、公開済みの Python パッケージを分離された環境にダウンロードして実行します。このリポジトリをクローンしたり、サーバーを別途起動したりする必要はありません。必要に応じて、IDE が stdio 経由でサーバーを起動します。

Cursor

Cursor の MCP 設定にこのサーバーを追加します。

{
  "mcpServers": {
    "secure-schema": {
      "command": "uvx",
      "args": ["mcp-secure-schema"],
      "env": {
        "DATABASE_URL": "postgresql+psycopg2://schema_reader:password@localhost:5432/appdb",
        "DATABASE_SCHEMA": "public",
        "ALLOWED_TABLES": "users,orders,products",
        "SECURE_SCHEMA_ENV": "production",
        "FASTMCP_CHECK_FOR_UPDATES": "off",
        "FASTMCP_SHOW_SERVER_BANNER": "false"
      }
    }
  }
}

MCP 設定を変更した後、Cursor を再起動するか再読み込みしてください。

Codex

~/.codex/config.toml または信頼できるプロジェクトの .codex/config.toml に追加します。

[mcp_servers.secure-schema]
command = "uvx"
args = ["mcp-secure-schema"]
enabled_tools = ["schema_overview", "list_tables", "inspect_table"]
startup_timeout_sec = 30
tool_timeout_sec = 30

[mcp_servers.secure-schema.env]
DATABASE_URL = "postgresql+psycopg2://schema_reader:password@localhost:5432/appdb"
DATABASE_SCHEMA = "public"
ALLOWED_TABLES = "users,orders,products"
SECURE_SCHEMA_ENV = "production"
FASTMCP_CHECK_FOR_UPDATES = "off"
FASTMCP_SHOW_SERVER_BANNER = "false"

代わりに一度だけインストールする

継続的にインストールしておく場合は、次のコマンドを実行します。

pipx install mcp-secure-schema

その後、IDE の設定で "command": "mcp-secure-schema" を指定し、args リストを空にします。

データベース URL

Secure Schema MCP は SQLAlchemy の接続 URL を受け付けます。

# SQLite (absolute path)
sqlite:////Users/me/project/app.db

# PostgreSQL
postgresql+psycopg2://user:password@localhost:5432/appdb

# Remote PostgreSQL with certificate verification
postgresql+psycopg2://user:[email protected]:5432/appdb?sslmode=verify-full&sslrootcert=/path/to/ca.pem

# MySQL
mysql+pymysql://user:password@localhost:3306/appdb

URL のユーザー名とパスワードに特殊文字が含まれる場合は、パーセントエンコードしてください。たとえば、パスワード内の @ は %40 になります。

ローカルデータベースとリモートデータベースで、同じ MCP 設定を使用できます。リモートデータベースの場合、IDE を実行するマシンで DNS、ネットワークアクセス、ファイアウォールの許可、適切な TLS 設定が機能している必要もあります。

設定

変数	必須	説明
DATABASE_URL	はい	SQLAlchemy の接続 URL。レジストリマニフェストではシークレットとして扱われます。
DATABASE_SCHEMA	いいえ	デフォルトのスキーマまたはカタログの名前空間。PostgreSQL では設定を推奨します。本番環境ではツールによる上書きが禁止されます。
ALLOWED_TABLES	本番環境	テーブル名とビュー名をカンマで区切った、大文字と小文字を区別する許可リスト。本番モードでは、これが設定されていないと起動できません。
SECURE_SCHEMA_ENV	いいえ	厳格な起動時検証を行うには、production または prod を設定します。デフォルトは development です。
FASTMCP_CHECK_FOR_UPDATES	いいえ	予測可能な stdio 起動にするには、off を設定します。
FASTMCP_SHOW_SERVER_BANNER	いいえ	起動バナーを非表示にするには、false を設定します。

複数のスキーマ

DATABASE_SCHEMA はデフォルトの名前空間を選択します。解決方法は次のとおりです。

• 本番環境では、設定された DATABASE_SCHEMA がセキュリティ境界となり、ツール引数で上書きできません。
• 本番環境以外では、明示的なツールの schema 引数が DATABASE_SCHEMA より優先されます。
• どちらも指定されていない場合は、データベースドライバーのデフォルトスキーマが使用されます。

複数のスキーマへのアクセスを本番環境で厳密に制御するには、スキーマごとに独自の DATABASE_SCHEMA と ALLOWED_TABLES を設定した MCP サーバーエントリーを実行してください。テーブルの許可リストには、スキーマ名で修飾されていないテーブル名を指定します。schema.table 形式の値は使用しません。

ツール

• schema_overview：許可されたテーブル、ビュー、主キー、外部キーのリレーションシップをまとめたコンパクトなマップ
• list_tables：許可されたテーブルとビューの一覧
• inspect_table：1 つのエンティティの列、SQL の型、NULL 許容性、主キー、一意制約、外部キー

すべてのツールは、トークン使用量を抑えるため、デフォルトで format="compact" を使用します。

tables:orders,users | pk:orders(order_id);users(user_id) | fk:orders.user_id->users.user_id

人が読みやすい表のほうが便利な場合は、format="markdown" を指定してください。

セキュリティに関する注意事項

• サーバーが公開するのは SQLAlchemy の検査操作のみで、行のクエリや書き込みを行うツールはありません。
• 許可リストが有効な場合、存在しないテーブル名と許可されていないテーブル名には同じメッセージが返され、テーブルの存在が漏れるのを防ぎます。
• クライアントに返すエラーはサニタイズされます。運用上の詳細はサーバーの標準エラー出力に書き込まれます。
• IDE が MCP プロセスを起動し、その環境を設定するため、IDE とその設定は信頼できるものとして扱ってください。
• 認証情報を含む設定をコミットしないでください。より強固に分離するには、OS のキーチェーンまたはシークレットマネージャーから DATABASE_URL を取得するラッパー経由で起動してください。
• 専用の最小権限のデータベースアカウントを使用し、リモート接続では TLS 証明書の検証を有効にしてください。

PostgreSQL のロールの例：

CREATE ROLE schema_reader LOGIN PASSWORD 'use-a-secret-manager';
GRANT CONNECT ON DATABASE appdb TO schema_reader;
GRANT USAGE ON SCHEMA public TO schema_reader;

メタデータの可視性は、PostgreSQL プロバイダーとデータベースポリシーによって異なります。検査に必要な追加のカタログまたはオブジェクト権限のみを付与してください。環境で必要な場合を除き、行に対する SELECT 権限は付与しないでください。

トラブルシューティング

サーバーがすぐに終了する

IDE の MCP ログを確認してください。DATABASE_URL は必須で、本番モードでは空でない ALLOWED_TABLES の値も必要です。

テーブルまたはビューが見つからない

DATABASE_SCHEMA、テーブル名の大文字・小文字、データベース権限、および許可リストに想定した名前が含まれているかを確認してください。

有効なパスワードを指定しても接続 URL が失敗する

URL の予約文字をパーセントエンコードするか、シークレットを注入するラッパーを使用してください。実際の認証情報をイシューやログに貼り付けないでください。

uvx が見つからない

公式の手順に従って uv をインストールするか、pipx でパッケージをインストールし、コマンドとして mcp-secure-schema を使用してください。

コマンドの起動時に処理が停止したように見える

stdio MCP サーバーでは正常な動作です。標準入力からの MCP クライアントを待機しており、通常は IDE によって起動されます。

開発

サーバーの開発またはテストを行う場合に限り、リポジトリをクローンしてください：

git clone https://github.com/Siddharth-coder13/secure_schema_mcp.git
cd secure_schema_mcp
uv sync --extra dev
uv run python tests/demo_database.py
DATABASE_URL="sqlite:///$PWD/test_schema.db" uv run mcp-secure-schema

テストスイートを実行します：

uv run pytest

使い捨てのデータベースに対して、オプトインの PostgreSQL 統合テストを実行します。このテストでは、ランダムな名前のスキーマを作成して削除します：

POSTGRES_TEST_DATABASE_URL='postgresql+psycopg2://user@localhost:5432/testdb' \
  uv run pytest tests/test_postgres_smoke.py -v

テストでは、行データの分離、許可リストの動作、サニタイズされたエラー、コンパクトな出力、リレーションシップ、スキーマの選択、および本番名前空間のロックを検証します。

リリースチェックリスト

メンテナーは pyproject.toml と server.json の対応するバージョンを更新し、SQLite と PostgreSQL の全テストスイートを実行して、uv build --no-sources でビルドし、ホイールからのインストールを確認して、PyPI に公開してください。その後にのみ、server.json を MCP Registry に公開してください。

ライセンス

Apache License 2.0 に基づいてライセンスされています。LICENSE と NOTICE を参照してください。