SQL Mini MCP

sql-safe-mcp

SQL Server、MySQL、MariaDB を扱うコーディングエージェント向けの、PII 安全な読み取り専用 MCP サーバーです。スキーマ情報と安全なクエリを提供し、書き込み可能なツールや、設定した PII 列の平文での露出はありません。

データを読み取り、個人情報を守る。

コーディングエージェントが正しいコードを書くために必要な、サーバー、データベース、テーブル、列、キー、インデックス、ストアドプロシージャなどのスキーマ情報を提供します。all_pii_safe に設定したエイリアスでは、設定済みの個人データを認証済みトークンの背後に隠したまま、実際の行をクエリすることもできます。

デフォルトで PII 安全。設計上、読み取り専用です。

• デフォルトで PII 安全 - all_pii_safe サーバーでは、設定した列の値はエイリアスに紐付いた認証済みトークン（pii:v1:...）として返され、平文では返されません。エージェントは、渡されたトークンを使って = や IN で列を射影、カウント、フィルタリングできるため、値を読み取らずにレコードを追跡できます。トークンは別のサーバーエイリアスや別のキーでは機能しません。
• 設計上、読み取り専用 - 7 つのツールはすべて読み取り専用として注釈されています。データを書き込むツールはなく、サーバーがエージェントの作成した SQL を実行することもありません。メタデータは SQLAlchemy Inspector と固定のカタログクエリから取得され、execute_sql は検証後に再生成した SELECT のみを実行します。
• 複数サーバーとポリシーの分離 - 1 つの MCP プロセスで、名前付きの複数の SQL Server、MySQL、MariaDB インスタンスを公開できます。各エイリアスは、それぞれ独自の接続、アクセスレベル、さらに有効な場合は PII キーと保護ルールを持ちます。すべてのデータベース操作では明示的なエイリアスを指定します。ネットワーク探索は行いません。

運用上の安全策

• フェイルクローズ方式 - SQL の検証には許可リストを使用します。不明な構文、解決できないリネージ、サポートされていない保護対象値の型は、推測せず拒否します。検証の証拠はセキュリティモデルに記載されています。
• アクセスは最小限から - access_level: metadata（デフォルト）では、データベースのナビゲーション情報とテーブル構造を公開します。meta_and_code では、さらにストアドプロシージャを公開します。execute_sql には、専用のキーを持つ明示的な all_pii_safe エイリアスが必要です。データベース権限を主要な制御として維持するため、最小権限のログインを使用してください。
• シークレットを表に出さない - 接続 URL は YAML に ${NAME} プレースホルダーとともに保存され、環境変数から解決されます。ログやモデルに表示されるエラーに含まれることはありません。
• コンパクトで予測可能な出力 - オブジェクトを起点とする結果、安定した並べ替え、大文字と小文字を区別しない名前のリテラルフィルター、定義を展開しないストアドプロシージャの一覧を提供します。
• エージェントが対処できるエラー - 名前があいまいな場合は、候補となるスキーマが表示されます。エラーに接続情報、認証情報、キー、トークン、行が含まれることはありません。
• 例だけでなく攻撃に対してもテスト済み - SQL と PII の境界は、悪意のあるステートメントを集めた敵対的コーパス、プロパティベーステスト（トークンの分離、改ざんへの耐性）、書き込み可能な実際のログインに対する攻撃の実行と実行前後のスナップショット、ミューテーションテストによって検証されています。結果はSQL 境界の検証に記載されています。
• 診断可能な障害 - タイムアウトや接続エラーには Reference が付与されます。stderr ログには、同じ参照に対応する接続段階、経過時間、ドライバーエラーが記録され、認証情報は削除されます。ログを参照してください。

メモ

ステータス： SQL Server はすべてのツールをサポートしています。MySQL と MariaDB（engine: mysql または mariadb、mysql+pymysql URL）もすべてのツールをサポートしています。これらではデータベースがカタログであるため、schema は常に null です。また、execute_sql では TOP の代わりに LIMIT を使用します。architecture.mdを参照してください。

クイックスタート

インストール

uvx sql-safe-mcp

または

pip install sql-safe-mcp

固定されたインターフェースを使う場合は、バージョンを固定してください：uvx sql-safe-mcp==1.5.2。

Python 3.12～3.14、uv（または pip）が必要です。SQL Server に接続する場合は、Microsoft ODBC Driver 18 for SQL Serverも必要です。MySQL と MariaDB では同梱の PyMySQL ドライバーを使用するため、ほかに必要なものはありません。

SQL Server 2022、MySQL 8.4、MariaDB 11.4 で検証済みです（checks.mdを参照）。

Install sql-safe-mcp as a stdio MCP server.
Ask whether to install it for this project/workspace or at user level. Then:
detect and preserve the host's existing MCP config;
configure the server to run via uvx sql-safe-mcp;
create a YAML config template with env placeholders only;
add SQL_SAFE_MCP_CONFIG;
report the env variables the user must set.
Do not store secrets or connection data in tracked files or output. Validate with
sql-safe-mcp --check-config once variables are available.

sql-safe-mcp.example-simple.yaml を sql-safe-mcp.yaml にコピーします。この最小構成では、1 つの SQL Server インスタンスのスキーマメタデータを公開し、行クエリは許可しません。接続 URL 全体は環境変数に保持します。

version: 1
servers:
  reporting:
    engine: sqlserver
    access_level: metadata
    connection_url: "${REPORTING_SQL_URL}"

ここで、reporting はエージェントが server として渡す値です。環境変数が未設定の場合、または engine が URL の方言と一致しない場合、起動時に MCP サーバーが停止します。複数のサーバー、ローカルの PII ルール、共有 PII ルールセット、ログ記録、実行時の制限については、設定リファレンスのコメント付きの例を使用してください。

設定を確認する

YAML ファイルで参照されるすべての環境変数を定義した後、SQL_SAFE_MCP_CONFIG（または --config）でサーバーの設定ファイルを指定し、データベースに接続せずに確認します。

SQL_SAFE_MCP_CONFIG=sql-safe-mcp.yaml uvx sql-safe-mcp --check-config

設定は起動時に検証され、エラーには問題点が示されますが、URL やシークレットは出力されません。認証情報はホスト独自の設定に保持し、絶対にコミットしないでください。サーバーはデータベースアカウントの権限で動作するため、ジョブに必要な最小限のアクセス権を持つ専用ログインを使用してください。

MCP クライアントを接続する

すべてのクライアント設定には SQL_SAFE_MCP_CONFIG と、YAML ファイルで参照される環境変数が必要です。接続 URL と PII キーは MCP ホストの環境または設定に保持し、YAML ファイルやその他の追跡対象ファイルには絶対に含めないでください。

claude mcp add --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-safe -- uvx sql-safe-mcp

{
  "mcpServers": {
    "sql-safe": {
      "command": "uvx",
      "args": ["sql-safe-mcp"],
      "env": {
        "SQL_SAFE_MCP_CONFIG": "/path/to/sql-safe-mcp.yaml",
        "REPORTING_SQL_URL": "mssql+pyodbc://..."
      }
    }
  }
}

codex mcp add sql-safe --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... -- uvx sql-safe-mcp

PII を保護するクエリ

billing エイリアスの execute_sql では、制限付きの SELECT を 1 つ実行できます。たとえば、次の引数を指定すると、

{
  "server": "billing",
  "database": "Billing",
  "sql": "SELECT CustomerId, Email FROM dbo.Customers"
}

[42, "pii:v1:..."] のような行を返すことができます。エージェントはメールアドレスを読み取らずに、顧客を追跡できます。トークンが受け入れられるのは、同じサーバーエイリアス上の = および IN の述語で使用された場合のみです。FirstName が保護されている場合、SELECT FirstName FROM Users WHERE FirstName = 'Alice' はデータベースに届く前に拒否されます。保護された列のフィルターには、同じエイリアスに対する execute_sql が返した真正な pii:v1:... トークンのみを使用してください。一致するプレフィックスだけでは不十分です。各トークンは認証されてエイリアスに紐付けられた後、検証され、バインドされたデータベース値に変換されます。保護の対象となるのは指定した列のみです。個人データを保持する列をすべて指定してください。

ドキュメント

• 設定リファレンス - エイリアス、接続 URL、PII ルール、実行時の制限、ログ記録。
• ツールリファレンス - 引数、応答、エラー、受け入れられる SQL のサブセット。
• セキュリティモデル - 信頼境界、保証、制限、検証。
• チェック - ローカル、統合、セキュリティの検証コマンド。

セキュリティ

MCP 呼び出し元、SQL 入力、データベースメタデータ、行、トークンは信頼できないものとして扱います。データベースの権限が引き続き主要な認可制御であり、このサーバーがその権限を拡大することはありません。制限と検証の証拠を含む、完全なセキュリティモデルをお読みください。脆弱性を報告する場合は、SECURITY.mdに記載された非公開の連絡経路を使用してください。

貢献

セットアップ、チェック、テストコマンド、ブランチとコミットの規約、リリースモデルについてはCONTRIBUTING.mdをご覧ください。サーバーを実行するユーザーに影響する変更はCHANGELOG.mdに記録します。

License

MIT.