Elekto MCP for SQL Server

Elekto.Mcp.Sql

SQL Server 2017 以降（2019 および 2022 でテスト済み）を調査し、クエリを実行するための読み取り専用 MCP サーバーです。 MCP プロトコル（stdio）を介してスキーマのメタデータ、オブジェクト定義、データクエリを公開し、 GitHub Copilot（および Claude などの他の MCP クライアント）が、リポジトリに認証情報を保存することなくデータベース構造を理解できるようにします。

⚠️ プライバシーとデータセキュリティに関する警告

MCP サーバーは、ローカルデータと AI 言語モデルの間の橋渡しとして機能します。このサーバーを AI アシスタント（GitHub Copilot、Claude など）と使用すると、次のことが起こります。

1. AI エージェントがこのサーバーのツールを呼び出し、SQL Server データベースからデータを読み取ります。
2. 結果（テーブルスキーマ、ストアドプロシージャの定義、実際の行データなどを含む場合があります）は AI エージェントに返され、分析のために LLM プロバイダーのインフラストラクチャに送信されます。
3. つまり、データはお使いのマシンから外部に出て、サードパーティのサービス （Microsoft、Anthropic、OpenAI など）に送信され、それぞれの利用規約と プライバシーポリシーが適用されます。

このサーバーをデータベースに接続する前に、次の点を慎重に検討してください。

• どのようなデータが読み取られる可能性がありますか？個人を特定できる情報、財務記録、企業秘密、 またはその他の機密情報が含まれていますか？
• LLM プロバイダーはどこですか？データ保持とプライバシーに関するポリシーはどのようなものですか？
• 適用される法律や規制の下で、このデータをサードパーティと共有する権限がありますか？

推奨事項：

• リスクを明示的に評価して受け入れていない限り、機密データを含むデータベースには接続しないでください。
• 必要最小限の権限を持つデータベースアカウントを使用してください（可能な場合は読み取り専用にし、特定のスキーマに制限してください）。
• 1 回の呼び出しで返されるデータ量を制限するには、max_query_rows を使用してください。
• 開発や調査には、匿名化または合成データを使用したデータベースを優先してください。
• AI エージェントはタスクを実行する方法を非常に創造的に見つけることがあります。このサーバーは 読み取り専用として設計され、すべての入力を検証しますが、AI エージェントにデータベースへのアクセスを公開すると、 意図しない結果が生じるリスクは常にあります。

どのような予防策を講じても、このツールの使用によって生じる結果に対する責任はすべて お客様が負うものとします。 このソフトウェアは、いかなる種類の保証もなく、現状のまま提供されます。

利用可能なツール

ツール	説明
list_databases	構成に登録されているデータベース
get_database_overview	データベースの概要（件数、サイズ、接続メタデータ）と、ログインユーザーがすべてを参照できるかどうか
check_permissions	接続中のログインユーザーが参照できるものとできないもの、それを解決する GRANT、および書き込み可能かどうか
get_schema_summary	スキーマごとの集計指標（オブジェクト、行数、サイズ）
list_schemas	データベース内のスキーマ（システムスキーマを除く）
list_tables	スキーマ、日付、概算行数、推定サイズを含むユーザーテーブル。スキーマと名前パターンで絞り込み可能
list_views	ユーザービュー。スキーマと名前パターンで絞り込み可能
find_columns	名前がパターンに一致する列を含む、すべてのテーブルとビュー
list_procedures	ユーザー定義のストアドプロシージャ（基本的な複雑度指標付き）
list_functions	ユーザー定義関数（基本的な複雑度指標付き）
get_table_schema	曖昧さのない型宣言を持つ列、すべての拡張プロパティ、PK、FK、CHECK、UNIQUE、およびキー順と宣言されたキー幅を含むインデックス
get_view_definition	ビューの DDL 定義と列（同じ列の詳細を含む）
get_procedure_definition	CREATE PROCEDURE テキスト
get_function_definition	CREATE FUNCTION テキスト
get_dependency_graph	オブジェクトの依存関係エッジ（FK および SQL の依存関係）
get_table_usage	FK と SQL モジュール全体にわたるテーブルへの参照
get_data_profile	列のプロファイル（NULL 比率、個別値の数、最小値／最大値、上位の値）
get_index_health	重複／未使用インデックスの診断と、インデックス不足の提案
compare_schemas	構成済みの 2 つのデータベース間でテーブル／列の構造を比較
generate_dependency_dot	ノードのメタデータ（node_kind）を含む Graphviz DOT 依存関係グラフ
query_table	フィルタリング、グループ化、安全な集計、ソート、サンプリング、ページネーションを用いてテーブルまたはビューから SELECT

1.x からのアップグレード

バージョン 2.0.0 では、ツールが返す内容とパラメーターの宣言方法が変更されています。再構成は不要です。接続ファイル、.mcp.json、CLI 引数に変更はありません。ただし、出力を解析するものは影響を受けます。

変更	対応方法
query_table は配列ではなくオブジェクトを返します	rows から行を読み取り、truncated を確認してください
エラーをツールエラーとして発生させる代わりに、ok: false の内容を返します	ペイロードをデータとして扱う前に、ok === false を確認してください
列の結果に type_declaration、max_length_chars、is_persisted、extended_properties が追加されました	バイト単位の max_length ではなく、type_declaration を優先してください
列の description は、extended_properties.MS_Description のエイリアスになりました	対応不要です。引き続き機能します
オプションのツールパラメーターは nullable ではなくなりました	MCP 経由では対応不要です。C# から直接呼び出す場合は、null の代わりに ""（または 0）を渡してください
新規：find_columns。list_tables と list_views は name_pattern を受け取ります	対応不要です。どちらも追加機能です

その他すべて、つまり他のすべてのツールとフィールドに変更はありません。

2.1.0 での変更点

形状に変更はありません。配列は引き続き配列であり、オブジェクトにもこれまでどおりすべてのフィールドが含まれます。一部の値は、事実を推測して返す代わりに「不明」とするようになりました。これらを解析する場合は、この点にご注意ください。

変更	理由
新機能：check_permissions	ツールごとに、ログインに不足している権限と、それを解決する GRANT を示します
get_database_overview、get_table_usage、get_index_health、generate_dependency_dot に visibility ブロックを追加	ログインから一部しか見えない結果であることを示すためです
list_procedures／list_functions の行に definition_visible を追加しました。値が false の場合、line_count と join_count は null になります	定義が非表示の場合、以前は 0 行の本体として表示されていました
ログインが sys.sql_expression_dependencies を読み取れない場合、referenced_object_count と get_table_usage の sql_module_usage は null になります	以前はどちらもエラー 229 で呼び出し全体が失敗していました
ログインにサーバー権限がない場合、get_index_health は重複を返し、DMV セクションは null にします	以前は、権限が不要な部分も失われ、呼び出し全体が失敗していました
ログインから見えない名前に対する get_*_definition は、[] ではなく ok: false を返します	[] では「存在しない」と「ログインから隠されている」を区別できませんでした
SQL エラーに番号が含まれ、ヒントで権限、名前の欠落、構文を区別します	以前は、3 つすべてに同じ汎用ヒントが使われていました

2.2.0 での変更点

ツールの結果の形状に変更はありません。変更されたのは、サーバーの起動方法とパッケージ方法です。

変更	理由
サーバーは接続がなくても起動し、サーバーの指示でそのことを伝えます。また、すべてのツールは ok: false とともに、作成するファイル、その検索場所、設定例を返します	起動時に終了するサーバーは「failed」としか表示されず、すべてのプロジェクトに登録すると、どのプロジェクトでも失敗していました
読み取れない設定（無効な JSON、設定されていない %{VARIABLE}、存在しないか空の --connections ファイル）は、プロセスを終了させる代わりに同じ方法で報告されます	エラーがツールの呼び出し元に届くようになりました
接続が読み込まれていない間は、呼び出しのたびに設定を再検索します	サーバー起動後に作成された接続ファイルも、再起動せずに使用できます
パッケージが nuget.org の MCP サーバー一覧に掲載され、.mcp/server.json を含むようになりました	そこから見つけられるようになり、MCP Server タブですぐ使える設定が提供されます

設定が見つからない場合や読み取れない場合でも、プロセスは終了コード 1 で終了しなくなりました。この終了コードに依存していた場合は、代わりにツールの応答を確認してください。README には、Claude Code と Codex のセットアップ手順も追加されました。

2.3.0 での変更点

ツールの結果の形状に変更はありません。変更されたのは、ツール自身についての説明です。エージェントはこれをもとにツールを選択します。

変更	理由
すべてのツールにタイトルと、MCP アノテーション readOnlyHint、idempotentHint、destructiveHint: false、openWorldHint: false を設定しました	クライアントはツールを安全なものとして表示でき、エージェントが説明文から推測する必要がなくなります
すべての説明に、ツールの機能、使用する場面、代わりに使うツールを記載しました	エージェントが 21 個のツールから最初から適切なものを選べるようにするためです
接続時にサーバーが常に指示を送信し、ツール同士の連携について説明します	以前は、接続が設定されていない場合にのみ指示を送信していました

2.3.1 での変更点

形状に変更はありません。generate_dependency_dot は、矢印の向き、DOT テキスト以外に返す内容、レンダリング方法、別のツールがより適している場面を説明するようになりました。サーバーは MCP Registry に「Elekto MCP for SQL Server」として掲載され、各リリースはリポジトリの GitHub Releases にも表示されるようになりました。

2.3.2 での変更点

形状に変更はありません。接続が設定されていない場合、エージェントに返されるガイダンスで、何かを書き込む前にユーザーの同意を得ること、また、パスワードを接続ファイルやほかの場所に書き込まず、代わりに %{VARIABLE} を使うことを伝えるようになりました。また、プロジェクトがすでに保持している可能性がある、このサーバーが参照しない接続情報（application.properties または application.yml の spring.datasource.url、あるいは .env ファイル内の sqlserver:// または mssql:// URL）も示します。これはサーバーが解析するためではなく、エージェントがユーザーに表示するためのものです。

2.3.3 での変更点

形状に変更はありません。このツールには System.Security.Cryptography.Pkcs 9.0.13 が含まれていました。これは Microsoft.Data.SqlClient が依存関係として取り込み、2 件の .NET サービス拒否に関する勧告の対象となっているものです：GHSA-846f-f764-76mx（CVE-2026-84008、高）および GHSA-2fmv-rv2c-59x7（CVE-2026-70162、中）。現在は修正版の 10.0.13 が含まれています。グローバルツールを dotnet tool update -g Elekto.Mcp.Sql で更新してください。バージョンを指定しない dnx の設定では、自動的に 2.3.3 が取得されます。

GitHub Release にパッケージとビルド来歴の証明が添付された最初のリリースでもあります。リリースの検証では、確認方法を説明しています。

2.3.4 での変更点

形状に変更はありません。このツールは Microsoft.Data.SqlClient 7.1.1（7.0.2 から更新）で動作するようになりました。このバージョンでは、接続プール、トランザクション、Named Pipes に関する修正が含まれています。また、Microsoft.Extensions.Hosting 10.0.12 も使用します。2.3.3 で導入された修正版の System.Security.Cryptography.Pkcs 10.0.13 は引き続き含まれています。パッケージは現在、Trusted Publishing のみを通じて nuget.org に公開されます。リリースワークフローでは、保存済みの API キーを使用しなくなりました。

結果の読み方

返されるデータの形状について、利用前に知っておくべきことが 3 つあります。

列の型は意図的に 2 通りで報告されます

sys.columns.max_length はバイト単位であると文書化されています。そのため、nvarchar(250) 列は 500 と報告されます。これを文字数として読み取ると 2 倍の誤りになります。後続の処理で矛盾が生じないため、気付かないままです。この生の値もカタログとの忠実性を保つために報告されますが、単独では決して返されません。

{
  "column_name": "Tag1",
  "data_type": "nvarchar",
  "type_declaration": "nvarchar(250)",
  "max_length": 500,
  "max_length_chars": 250
}

type_declaration または max_length_chars を使用してください。読み違えることはありません。

列には extended_properties（MS_Description だけでなく、すべてのプロパティ）も含まれるため、アプリケーション独自の規約（表示形式、単位、マスク）を確認できます。また、計算列には is_persisted も含まれます。

query_table は配列だけでなく、エンベロープを返します

2 行の配列だけでは、2 行を含むテーブルと区別できません。そのため、結果にはデータの種類が示されます。

{
  "table": { "schema": "Feeder", "name": "GenericSecurity" },
  "row_count": 100,
  "truncated": true,
  "top_applied": 100,
  "skip": 0,
  "max_query_rows": 10000,
  "rows": [ ... ]
}

truncated は推測ではなく、実測値です。上限を 1 行超えて取得し、その行を破棄します。top_requested は、max_query_rows によって要求された値が上書きされた場合にのみ表示されます。

失敗はコンテンツとして返されます

MCP ツールからスローされた例外は呼び出し元には届きません。ホストが汎用的なメッセージに置き換えます。そのため、失敗は ok: false を含む通常の結果として返されます。

{
  "ok": false,
  "tool": "query_table",
  "error": "'columns' looks like JSON: [\"Source\", \"Name\"]",
  "hint": "'columns' is a plain comma-separated string, not a JSON array or object.",
  "example": { "columns": "Source, Name, ReferenceDate" }
}

意図的なトレードオフです。ホストは呼び出しをエラーとしてマークしなくなりますが、呼び出し元は問題の内容を読み取り、修正できます。成功した結果は変更されず、ok フィールドを含みません。

ログインから見えないものは、エラーなしで除外されます

SQL Server は、ログインが何らかの権限を持つオブジェクトのみを表示し（メタデータの可視性）、それ以外は通知せずに除外します。db_datareader のみを持つログインにはすべてのテーブルが表示されますが、実行権限のないプロシージャは1つも表示されず、ビューは表示されてもそのテキストは表示されません。そのため、カタログへのクエリはどれも正常な形式の短い結果を返します。たとえば、実際には672個あるのに、「このデータベースにはプロシージャが6個あります」と返します。

データからはそれを明らかにできないため、サーバーはその原因となる権限を確認し、その結果を報告します。最初に呼び出すツールである get_database_overview は、次の情報を含みます。

"visibility": {
  "complete": false,
  "notes": [
    "The login lacks VIEW DEFINITION on the database. SQL Server then leaves out, without any error, every procedure, function and view the login holds no permission on, so their listings and counts may be short.",
    "756 of the 756 visible views, procedures and functions have their definition hidden from this login."
  ],
  "hint": "Call check_permissions for what this login is missing and the GRANT statements that fix it."
}

次に check_permissions は、ツールのグループごとに complete、partial、unavailable のいずれかを報告し、不足している権限と、それを付与する GRANT をサーバーのバージョンに合った構文で示します。また、write_access も報告します。これは、ロール、データベース権限、スキーマレベルまたはオブジェクトレベルの GRANT によって、ログインが何かを変更できるかどうかを示すものです。これにより、読み取り専用として意図されたアカウントについて、推測に頼らず確認できます。

インストール

.NET グローバルツールとして（推奨）

.NET 10 Runtime または SDK が必要です。

dotnet tool install -g Elekto.Mcp.Sql

新しいバージョンにアップグレードするには：

dotnet tool update -g Elekto.Mcp.Sql

インストール後、elekto-mcp-sql コマンドを PATH から利用できます。 パスを指定せず、.mcp.json で直接使用してください。

{
  "servers": {
    "sql": {
      "type": "stdio",
      "command": "elekto-mcp-sql"
    }
  }
}

設定不要： プロジェクトにすでに appsettings.json、web.config、または App.config の ConnectionStrings セクションがある場合、サーバーはそれを自動的に読み込むため、追加の設定は不要です。

Claude Code と Codex については、Claude Code のセットアップとCodex のセットアップを参照してください。

インストールせずに使用する（dnx）

.NET 10 SDK（ランタイムのみでは不可）には dnx が含まれています。これを使うと、dotnet tool install を実行せずに、NuGet からパッケージをダウンロードして実行できます。

{
  "servers": {
    "sql": {
      "type": "stdio",
      "command": "dnx",
      "args": ["Elekto.Mcp.Sql", "--yes"]
    }
  }
}

このパッケージは、nuget.org の MCP サーバー一覧に掲載されています。その MCP Server タブには、VS Code または Visual Studio に貼り付けてすぐに使える設定が表示されます。

ローカルで発行したファイルから（ネットワーク接続のない環境／企業環境向け）

cd src
dotnet publish -c Release -o C:\Tools\Elekto.Mcp.Sql

{
  "servers": {
    "sql": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["C:\\Tools\\Elekto.Mcp.Sql\\Elekto.Mcp.Sql.dll"]
    }
  }
}

設定

--connections <path> を指定すると、そのファイルのみが使用され、ほかの設定元は参照されません。

指定しない場合は、以下のすべての設定元が読み込まれ、統合されます。そのため、ある設定元で定義されたデータベースと、別の設定元で定義されたデータベースの両方を利用できます。同じデータベース名が複数の設定元に存在する場合は、優先順位の高い設定元が使用されます。

優先順位	設定元
1（最高）	作業ディレクトリ（プロジェクトルート）の .elekto.mcp.sql.local.json
2	appsettings.Development.json の ConnectionStrings
3	appsettings.json の ConnectionStrings
4	App.config / web.config の <connectionStrings>
5	ユーザーのホームディレクトリ（~）にある .elekto.mcp.sql.local.json
6（最低）	MCP_SQL_CONNECTIONS 環境変数（旧形式との互換性のため）

ホームディレクトリのファイルは、プロジェクトの appsettings.json よりも優先順位が低い点に注意してください。ホームディレクトリのファイルにはデフォルト値を設定し、使用するプロジェクト側でそれを上書きします。

起動時、サーバーは読み込みに使用したすべての設定元を標準エラー出力に記録するため、どのファイルが有効になっているかを簡単に確認できます。

既存の .NET プロジェクトなら設定不要

プロジェクトに ConnectionStrings セクションを含む appsettings.json または web.config がすでにある場合、サーバーはそれを自動的に読み込みます。追加のファイルは必要ありません。

注意：自動検出は便利ですが、AI エージェントで安全に使用するには権限が強すぎるプロジェクト接続が使われる可能性があります。 既存の接続文字列に書き込み権限や機密データへのアクセス権がある場合は、読み取り専用の認証情報を使った別の接続ファイルを用意し、--connections で明示的に指定するか、プロジェクトのルートに配置することを検討してください。

接続ファイルの形式

このファイルは、論理データベース名と設定を対応付ける JSON オブジェクトです。

シンプルな形式（接続文字列を直接指定）：

{
  "MyDatabase": "Server=SQLSRV01\\INST;Database=MyDatabase;Integrated Security=SSPI"
}

完全な形式（オプションを指定）：

{
  "MyDatabase": {
    "connection_string": "Server=SQLSRV01\\INST;Database=MyDatabase;Integrated Security=SSPI",
    "max_query_rows": 5000,
    "default_timeout_seconds": 30
  }
}

どちらの形式も、同じファイル内で混在させることができます。すぐに使えるサンプルについては、sample-connections.json を参照してください。

ローカルファイルの推奨配置場所は、プロジェクトのルート（自動検出されます）または ~（すべてのプロジェクトで共有）です。このファイルには認証情報を保存することがあるため、このリポジトリと同様に、プロジェクトの .gitignore に .elekto.mcp.sql.local.json を追加してください。

データベースごとのオプション

オプション	型	デフォルト	説明
connection_string	文字列	必須	SQL Server の接続文字列
max_query_rows	整数	10 000	クエリ呼び出しごとに返される最大行数
default_timeout_seconds	整数	30	SQL コマンドのタイムアウト（秒）

接続文字列での環境変数の展開

認証情報を平文で保存しないよう、接続文字列内で %{VARIABLE_NAME} を使用してください。変数はサーバーの起動時にプロセス環境から解決されます。

{
  "CRM": {
    "connection_string": "Server=SQLSRV01;Database=CRM;User Id=%{CRM_DB_USER};Password=%{CRM_DB_PASS}",
    "max_query_rows": 2000
  }
}

%{CRM_DB_USER} と %{CRM_DB_PASS} は、対応する OS 環境変数の値に置き換えられます。参照先の変数が存在しない場合、接続は読み込まれず、すべてのツールで不足している変数が示されます（接続が設定されていない場合を参照）。

フォールバック：MCP_SQL_CONNECTIONS 環境変数

--connections が指定されていない場合、サーバーはフォールバックとして MCP_SQL_CONNECTIONS 環境変数を読み込みます。この環境変数には JSON を直接指定する必要があります。これは後方互換性のために用意されており、ファイルを使う方法を推奨します。

接続が設定されていない場合

接続が見つからない場合や、設定を読み込めない場合（JSON が無効、%{VARIABLE} が未設定、--connections で指定したファイルが存在しない場合）でも、サーバーは起動します。 起動時に終了するサーバーは、MCP クライアント上で「failed」と表示されるだけで、理由はログを確認しないとわかりません。一方、応答するサーバーなら、不足しているものを伝えられます。そのため、サーバーは次のように動作します。

• サーバーの指示に問題を記載し、クライアントは接続時にそれをモデルへ渡します。
• すべてのツールで、問題の内容、作成すべきファイル、確認したすべての場所、内容の例とともに ok: false を返します。

{
  "ok": false,
  "tool": "list_databases",
  "error": "No database connection is configured: none of the places this server reads holds a connection string.",
  "hint": "Ask the user for a SQL Server connection string, preferably of a login that can only read, and save it in the file named in 'setup.file', with the shape shown in 'example'. ...",
  "example": {
    "MyDatabase": "Server=SQLSRV01;Database=MyDatabase;Integrated Security=True;TrustServerCertificate=True",
    "Reporting": { "connection_string": "...User Id=%{REPORTING_USER};Password=%{REPORTING_PASS}...", "max_query_rows": 5000 }
  },
  "setup": {
    "file": "C:\\Projects\\Risk\\.elekto.mcp.sql.local.json",
    "file_for_every_project": "C:\\Users\\YourName\\.elekto.mcp.sql.local.json",
    "searched": [ "C:\\Projects\\Risk\\.elekto.mcp.sql.local.json", "ConnectionStrings in C:\\Projects\\Risk\\appsettings.Development.json", "..." ],
    "notes": [ "..." ],
    "documentation": "https://github.com/elekto-com-br/elekto-mcp-sql#configuration"
  }
}

• 接続が何も読み込まれていない間は呼び出しのたびに再確認します。そのため、あとから（あなたが作成した場合も、接続文字列を渡したあとにエージェントが作成した場合も）作られた接続ファイルは、再起動なしで次の呼び出しから使用されます。

接続を読み込んだあとは、サーバーを再起動するまでその接続が保持されます。そのため、すでに読み込まれたファイルを変更した場合は、サーバーを再起動する必要があります（Claude Code の場合は /mcp を実行して再接続し、Codex の場合は Codex を再起動します）。

Claude Code のセットアップ

ツールをインストールし（インストールを参照）、claude mcp add で登録します。 -- 以降は、Claude Code が実行するコマンドです。

dotnet tool install -g Elekto.Mcp.Sql
claude mcp add sql -- elekto-mcp-sql

Claude Code はプロジェクトディレクトリでサーバーを起動するため、Visual Studio と同様に、引数を指定しなくてもゼロ設定の検出が機能します。プロジェクト内にある .elekto.mcp.sql.local.json、または appsettings.json / web.config の ConnectionStrings が検出されます。

-s（--scope）では、登録を保存する場所を選択します。

スコープ	コマンド	適用範囲
local（デフォルト）	claude mcp add sql -- elekto-mcp-sql	あなた専用のこのプロジェクト（~/.claude.json に保存）
user	claude mcp add -s user sql -- elekto-mcp-sql	あなたのすべてのプロジェクト
project	claude mcp add -s project sql -- elekto-mcp-sql	クローンしたすべての人が使えるこのプロジェクト（.mcp.json に書き込み）

-s user で登録すると、データベースのないプロジェクトでもサーバーが起動します。その場合、ツールは失敗する代わりに、接続の追加方法を案内します（接続が設定されていない場合を参照）。

その他の形式：

# An explicit connections file; no other source is read
claude mcp add sql -- elekto-mcp-sql --connections C:\Users\YourName\sql-connections.json

# Without installing the tool (needs the .NET 10 SDK, which brings dnx)
claude mcp add sql -- dnx Elekto.Mcp.Sql --yes

Windows では、インストールされたコマンドは実行ファイル（%USERPROFILE%\.dotnet\tools\elekto-mcp-sql.exe）そのものなので、npx 経由で起動するサーバーとは異なり、cmd /c のラッパーは必要ありません。

シークレット。 claude mcp add -e NAME=value は値を ~/.claude.json に平文で保存します。-s project の場合は、通常コミットされる .mcp.json に保存します。パスワードには、接続文字列に %{NAME} と記述し、代わりにユーザーアカウントの環境変数として NAME を設定してください。Claude Code は環境変数をサーバーに引き継ぎます。

claude mcp list で登録を確認します（サーバーに Connected と表示されます）。または、Claude Code 内で /mcp を使うと、ツールの一覧を確認でき、サーバーも再接続されます。

Claude Code 用に手動で記述する .mcp.json では、mcpServers キーを使用します。Visual Studio と VS Code では servers を使用します。

{
  "mcpServers": {
    "sql": {
      "type": "stdio",
      "command": "elekto-mcp-sql",
      "args": []
    }
  }
}

Codex のセットアップ

Codex は、OpenAI のコーディングエージェント（CLI、IDE 拡張機能、アプリ）で、ローカルの MCP サーバーも実行できます。ツールをインストールし（インストールを参照）、codex mcp add で登録します。-- 以降は、Codex が実行するコマンドです。

dotnet tool install -g Elekto.Mcp.Sql
codex mcp add sql -- elekto-mcp-sql

これによりサーバーが ~/.codex/config.toml（Windows では %USERPROFILE%\.codex\config.toml）に追加され、すべてのプロジェクトに適用されます。

[mcp_servers.sql]
command = "elekto-mcp-sql"

Codex はプロジェクトディレクトリでサーバーを起動するため、ここでもゼロ設定の検出が機能します。データベースのないプロジェクトでは、ツールが接続の追加方法を案内します（接続が設定されていない場合を参照）。

1 つのプロジェクトだけにサーバーを登録するには、代わりに同じテーブルをプロジェクトルートの .codex/config.toml に記述します。Codex は、信頼済みとしてマークされたプロジェクトでのみこのファイルを読み込みます。

codex mcp list と codex mcp get sql で設定を確認できます。claude mcp list とは異なり、これらのコマンドはサーバーを起動しないため、コマンドの誤りが判明するのは Codex のセッション開始時です。

環境変数は引き継がれません

Claude Code とは異なり、Codex はすべての環境変数ではなく、独自の限られた環境変数（HOME や PATH など）を使って MCP サーバーを起動します。そのため、接続文字列内の %{VARIABLE} は、環境から引き継ぐために env_vars に記載しない限り見つかりません。

[mcp_servers.sql]
command = "elekto-mcp-sql"
env_vars = ["CRM_DB_USER", "CRM_DB_PASS"]

これを設定しなくてもサーバーは起動しますが、各ツールは見つからなかった環境変数の名前を示します。

codex mcp add --env NAME=value では値を直接設定できます（env テーブル）。ただし、値は config.toml に平文で保存されるため、シークレットではない値に使用してください。

その他の形式

ほかのソースを読み込まない、明示的な接続ファイル：

[mcp_servers.sql]
command = "elekto-mcp-sql"
args = ["--connections", 'C:\Users\YourName\sql-connections.json']

Windows のパスは 単一引用符 で囲みます。TOML ではそのままの文字列として扱われるためです。二重引用符で囲むと、C:\Users の \U がエスケープシーケンスとして読み取られ、Codex はファイル全体を拒否します。二重引用符を使う場合は、すべてのバックスラッシュを二重にする必要があります。codex mcp add は単一引用符を自動的に記述します。

ツールをインストールせずに使う場合（.NET 10 SDK が必要です。dnx も含まれています）：

[mcp_servers.sql]
command = "dnx"
args = ["Elekto.Mcp.Sql", "--yes"]
startup_timeout_sec = 30

初回起動時にパッケージをダウンロードします。この処理は、Codex が通常サーバーを待機する時間より長くかかることがあります。startup_timeout_sec を設定すると、待機時間を延長できます。インストール済みのツールは 1 秒未満で起動するため、この設定は不要です。

Codex が WSL 内で実行されている場合、サーバーは Linux 内で起動しますが、Linux からは Windows にインストールされたツールを参照できません。WSL にも .NET とツールをインストールしてください。Linux から Integrated Security を使うには、Kerberos の設定も必要です。パスワードを env_vars に指定した %{VARIABLE} に格納して使う SQL Server ログインのほうが簡単です。

Visual Studio 2026 のセットアップ（.mcp.json）

ソリューションのルート（またはグローバルに使う場合はユーザープロファイル）に .mcp.json を作成するか、編集します。

推奨：ローカル接続ファイル（設定不要）

プロジェクトのルートまたは ~ に .elekto.mcp.sql.local.json ファイルを置くと、サーバーが自動的に検出します。.mcp.json に引数を指定する必要はありません：

{
  "servers": {
    "sql": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["D:\\Tools\\Elekto.Mcp.Sql\\Elekto.Mcp.Sql.dll"]
    }
  }
}

代替方法：--connections でパスを明示する

--connections を使って、任意のファイルをサーバーに指定します。ファイルがプロジェクトツリーの外にある場合や、プロファイルを切り替える必要がある場合に便利です：

{
  "servers": {
    "sql": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "D:\\Tools\\Elekto.Mcp.Sql\\Elekto.Mcp.Sql.dll",
        "--connections",
        "C:\\Users\\YourName\\sql-connections.json"
      ]
    }
  }
}

接続ファイルはリポジトリの外に置いたままにするため、認証情報がソース管理にコミットされることはありません。

代替方法：環境変数（従来方式）

ファイルを使わない場合は、引き続き環境変数で JSON を渡すこともできます。JSON 内の JSON では、バックスラッシュを二重にエスケープする必要があることに注意してください（\\\\）：

{
  "servers": {
    "sql": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["D:\\Tools\\Elekto.Mcp.Sql\\Elekto.Mcp.Sql.dll"],
      "env": {
        "MCP_SQL_CONNECTIONS": "{\"MyDb\": {\"connection_string\": \"Server=SQLSRV01\\\\INST;Database=MyDb;Integrated Security=SSPI\"}}"
      }
    }
  }
}

.mcp.json を保存すると、Copilot がサーバーを自動的に再起動します。 ツールはデフォルトで無効になっています。Copilot Chat のツールパネルで有効にしてください。

ビルドと公開

cd Elekto.Mcp.Sql\src
dotnet publish -c Release -o C:\Tools\Elekto.Mcp.Sql

マシンに .NET 10 がインストールされている必要があります。公開ディレクトリのサイズは約 7 MB です（NuGet の依存関係を含む）。 内部利用では、自己完結型（約 81 MB）よりもこちらを推奨します。

dotnet pack は src/.mcp/server.json もパッケージ化します。このファイルには、サーバーの起動方法を nuget.org に伝える情報が記載されています。リポジトリ内のファイルでは、バージョンが入る箇所に $version$ が記載されており、パック時にその箇所がパッケージ化するバージョンに置き換えられるため、リリース時にこのファイルを更新する必要はありません。

各タグの作成時には、nuget.org が新しいバージョンをインデックス化した後、サーバーを MCP Registry に io.github.elekto-com-br/elekto-mcp-sql として公開します。レジストリがこのパッケージを当社のものとして受け入れるには、README に mcp-name: io.github.elekto-com-br/elekto-mcp-sql という行が含まれている必要があります。そのため、このファイル先頭のコメントは残しておく必要があります。パック後の README からこの行が失われると、CI が失敗します。

パッケージのバージョンは src/packages.lock.json と tests/packages.lock.json で固定されています。PackageReference を変更した後は、dotnet restore を実行し、ロックファイルも一緒にコミットしてください。CI とリリース時の復元処理ではロックモードを使うため、ロックファイルがプロジェクトと一致しない場合は失敗します。

リリースの検証

2.3.2 以降のリリースには、GitHub Release にパッケージが含まれており、このリポジトリの公開ワークフローとリリースタグにひも付けられたビルド来歴証明が付与されています。GitHub CLI で確認するには：

gh release download vX.Y.Z --repo elekto-com-br/elekto-mcp-sql --pattern '*.nupkg'
gh attestation verify Elekto.Mcp.Sql.X.Y.Z.nupkg --repo elekto-com-br/elekto-mcp-sql

nuget.org が配布するコピーには nuget.org 独自のリポジトリ署名も付与されているため、来歴証明付きのファイルとは異なります。この署名は dotnet nuget verify で確認できます。

テストの実行

リポジトリのルートから：

dotnet test

テストプロジェクトには、次の 2 種類のテストがあります。

• ユニットテスト（ConnectionConfigTests など）には、.NET SDK 以外は必要ありません。
• 統合テスト（SchemaReaderTests）は実際の SQL Server に対して実行されます。実行のたびに ElektoMcpTest という名前のデータベースを作成し、小規模なシードスキーマを投入して、最後に削除します。

統合テストは次の順に SQL Server を探し、最初に見つかったものを使用します。

1. ELEKTO_MCP_SQL_CONN_TEST 環境変数。 設定されている場合、テストで使用可能なサーバーへの接続 文字列を指定する必要があります。接続文字列内のデータベース名は、指定されていても無視されます。ログインには、データベースを作成および削除する権限が必要です。このサーバーに接続できない場合は、次の選択肢を試さず、ただちにテストが失敗します。明示的に選択した接続先が機能しないことは、確認すべきエラーだからです。
2. LocalDB。 Windows で、(localdb)\MSSQLLocalDB インスタンスから応答がある場合に限ります。
3. 破棄可能なコンテナー。 Testcontainers を介して mcr.microsoft.com/mssql/server:2022-latest イメージから起動します。Docker が必要です（rootless Docker も使用できます）。統合テストで必要になった場合にのみコンテナーが起動し、実行終了時に削除されます。初回実行時にはイメージもダウンロードするため、時間がかかります。

どの選択肢も利用できない場合、統合テストは試した内容と各選択肢が機能しなかった理由を示すメッセージとともに失敗します。テスト出力には、使用したサーバーが表示されます。

一部の統合テストは、SQL Server によってオブジェクトが隠されている場合にツールが返す内容を確認するため、権限を制限したログインで実行されます。フィクスチャはこれらのログイン（ElektoMcpTest_*）を作成し、最後に削除します。そのため、ALTER ANY LOGIN 権限も必要です。この権限がサーバーで許可されていない場合、理由を示したうえで該当テストはスキップされます。

既存のサーバーをテストに指定する例：

export ELEKTO_MCP_SQL_CONN_TEST="Server=localhost,1433;User Id=sa;Password=<password>;TrustServerCertificate=True"
dotnet test

ELEKTO_MCP_SQL_CONN_TEST を、ElektoMcpTest というデータベースを誰かが必要としているサーバーに指定しないでください。テストでは、そのデータベースを削除して再作成します。

SQL Server を使用せず、ユニットテストだけを実行するには：

dotnet test --filter "FullyQualifiedName!~SchemaReaderTests"

推奨される権限

ツールが読み取るすべての情報にアクセスでき、変更権限は付与しない場合：

USE [YourDatabase];
CREATE USER [mcp_reader] FOR LOGIN [mcp_reader];  -- if the user does not exist yet
ALTER ROLE db_datareader ADD MEMBER [mcp_reader];  -- tables and views; also covers sys.sql_expression_dependencies
GRANT VIEW DEFINITION TO [mcp_reader];             -- procedures, functions, view text, complete dependencies

USE master;
GRANT VIEW SERVER STATE TO [mcp_reader];           -- get_index_health: unused and missing indexes

SQL Server 2022 以降では、最後の権限を、インデックス DMV が実際に必要とする権限に限定できます。

USE master;
GRANT VIEW SERVER PERFORMANCE STATE TO [mcp_reader];

権限	権限がない場合
db_datareader（データベースに対する SELECT）	ログインに権限が付与されていないテーブルとビューは対象から除外され、それらに対する query_table は失敗します。ログインが db_datareader に含まれていない場合は、sys.sql_expression_dependencies に対する GRANT SELECT ON sys.sql_expression_dependencies も必要です
データベースに対する VIEW DEFINITION	プロシージャと関数は対象から除外され、ビューとモジュールのテキストは非表示になり、依存関係の情報は不完全になります
VIEW SERVER STATE（2022 以降：VIEW SERVER PERFORMANCE STATE）	get_index_health は重複インデックスのみを返します

これらの権限では、ログインによるデータやスキーマの変更はできません。データベースに対して check_permissions を実行すると、不足している権限を確認できます。ログインとサーバーのバージョンに応じた SQL 文が出力されます。

制限とセキュリティ

• 読み取り専用です。テーブルとビューに対する SELECT のみが可能です。DML とプロシージャ／関数の実行はサポートされていません。
• query_table は、検証済みのパラメーターから内部で SQL を組み立てます。識別子（テーブル、スキーマ、列）は、SQL に組み込まれる前に正規表現で検証されます。
• WHERE 句は柔軟性を確保するため、自由形式のテキストとして受け付けます。ただし、コマンドは常に SELECT TOP n ... FROM [t] WHERE ... として組み立てられるため、DML は実行できません。
• max_query_rows は、データベースごとに返される行数の上限を設定します（既定値は 10,000）。query_table の top パラメーターは常にこの値以下に制限されます。また、結果が黙って短く返されるのではなく、top_requested と truncated によってその旨が示されます。
• それでも、信頼できない環境や機密データを扱う環境では、このサーバーを公開しないでください。ファイアウォールとアクセスポリシーを使用して、MCP 経由でクエリを実行できるユーザーを制限してください。設定済みのすべての接続で、必要最小限の権限（読み取り専用）を持つデータベースアカウントを使用してください。