Local Kms Mcp

local-kms-mcp-server

エージェントごとの鍵管理に対応した、ローカルファーストで軽量なMCP サーバーです。

外部 KMS に依存したり、秘密鍵を公開したりすることなく、各エージェントに独自の署名 ID を与えられます。

local-kms-mcp-server は、署名用の鍵ペアをすべてローカルマシン上で生成、保存、ローテーションし、使用します。鍵が プロセスの外に出たり、ネットワークに触れたりすることはなく、常に制御下にあります。

DID／SSI フロー、認証ハンドシェイク、チャレンジへの署名など、エージェントが暗号技術を使って何かを証明する必要があるワークフローで、分離可能かつ組み合わせ可能な ID を必要とする MCP クライアントやエージェントランタイム向けに構築されています。

提供する機能

• keyId に紐づけた署名用の鍵ペアを生成します（エージェントまたはタスクごとに 1 つの ID）
• シンプルなファイルベースのキーストアを使って、鍵をローカルに保存します
• 秘密鍵の情報を一切公開せずに、Base64 ペイロードに署名します
• アルゴリズムの整合性を維持しながら、安全に鍵をローテーションします
• 必要に応じて安全な消去（ランダムデータによる上書き）を行い、鍵を削除します
• 使用可能な署名アルゴリズムと鍵を一覧表示します
• 必要に応じて AES-256-GCM で保存時の鍵を暗号化します
• MCP 経由で stdio（デフォルト）または必要に応じて HTTP を使って実行します

対応アルゴリズム

アルゴリズム	ツールの値	備考
Ed25519	ed25519	汎用的な署名や DID 形式のユースケースに適したデフォルト
ECDSA secp256k1	ecdsa-secp256k1	Ethereum、Bitcoin、その他の Web3 フローで一般的
ECDSA P-256	ecdsa-prime256v1	ES256、WebAuthn、および一般的なクラウド KMS との互換性
ECDSA P-384	ecdsa-secp384r1	より高いセキュリティが求められる NIST P-384 環境

要件

• Node.js >=24.0.0
• stdio または HTTP の MCP サーバーに対応した MCP クライアント

クイックスタート

Stdio トランスポート

Claude Desktop、Cursor、その他のローカル MCP クライアントから実行する場合は、stdio を使います。

{
  "mcpServers": {
    "local-kms": {
      "command": "npx",
      "args": ["-y", "local-kms-mcp-server"],
      "env": {
        "STORE_PATH": "/Users/yourname/.local-kms",
        "ENCRYPT_STORE": "true",
        "STORE_ENCRYPTION_KEY": "<base64-32-byte-key>"
      }
    }
  }
}

HTTP トランスポート

ローカルネットワークのエンドポイントが明示的に必要な場合に限り、HTTP を使います。

TRANSPORT=http PORT=8080 npx local-kms-mcp-server

エンドポイント：

POST http://localhost:8080/mcp

インストール

npx から直接実行します：

npx -y local-kms-mcp-server

または、グローバルにインストールします：

npm install -g local-kms-mcp-server
local-kms-mcp-server

設定

環境変数	デフォルト	説明
STORE_PATH	./keys	保存する鍵ファイルのディレクトリ
TRANSPORT	stdio	MCP トランスポート：stdio または http
PORT	8080	TRANSPORT=http の場合にのみ使用する HTTP ポート
ENCRYPT_STORE	false	true または 1 に設定すると、保存時に鍵ファイルを暗号化します
STORE_ENCRYPTION_KEY	なし	暗号化を有効にする場合に必要な、Base64 エンコードされた 32 バイトの鍵

ローカル開発用のサンプルファイルは .env.example にありますが、実際に MCP クライアントから使う場合は、起動を確実に再現できるよう、クライアントの env 設定を通じて値を渡すことをおすすめします。

暗号化キーを生成します：

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

ツールリファレンス

すべてのツール入力は Zod で検証されます。公開鍵と署名は base64 文字列で返されます。

ツール	目的	入力	出力
check_keypair	キーが存在するか確認する	{ "keyId": "agent-1" }	{ "exists": true }
list_keys	保存されているすべてのキー ID を一覧表示する	{}	{ "keys": ["agent-1", "agent-2"] }
list_algorithms	サポートされているすべての署名アルゴリズムを一覧表示する	{}	{ "algorithms": ["ed25519", ...] }
generate_key	新しいキーペアを作成して保存する	{ "keyId": "agent-1", "algo": "ed25519" }	{ "publicKey": "..." }
get_key_info	キー ID に対応する保存済みの公開鍵を返す	{ "keyId": "agent-1" }	{ "publicKey": "..." }
rotate_key	保存されているアルゴリズムを使って既存のキーペアをローテーションする	{ "keyId": "agent-1" }	{ "newPublicKey": "..." }
delete_key	オプションの安全な消去機能を使ってキーペアを削除する	{ "keyId": "agent-1", "secureWipe": true }	{ "success": true }
sign_message	base64 エンコードされたペイロードに署名する	{ "keyId": "agent-1", "message": "aGVsbG8=" }	{ "signature": "..." }

注：

• keyId がすでに存在する場合、generate_key は失敗します
• rotate_key は保存されている version をインクリメントします
• secureWipe: true を指定した delete_key は、削除前にキーのファイルをランダムなデータで上書きします
• sign_message では、message がすでに base64 エンコードされている必要があります
• sign_message ではオプションで algo を上書きできますが、通常は保存済みのアルゴリズムを使うのが適切です

一般的な使用手順

1. list_algorithms を呼び出して、利用可能な署名アルゴリズムを確認します
2. 新しい keyId に対して generate_key を呼び出します
3. get_key_info を呼び出して、登録または配布用の公開鍵を取得します
4. エージェントがチャレンジやペイロードに署名する必要があるときは、sign_message を呼び出します
5. 同じ keyId の新しい鍵素材が必要なときは、rotate_key を呼び出します
6. キーペアが不要になったら、delete_key を呼び出して安全に削除します
7. 存在確認や一覧の取得には、check_keypair または list_keys を呼び出します

sign_message のペイロード例：

{
  "keyId": "key-1",
  "message": "eyJub25jZSI6IjEyMyJ9"
}

ストレージモデル

暗号化されていないキーは ${STORE_PATH} の下に、キーごとに 1 つのファイルとして保存されます。

${STORE_PATH}/${keyId}.json

保存されるレコードには次の内容が含まれます。

{
  "keyId": "key-1",
  "algo": "ed25519",
  "publicKey": "...",
  "privateKey": "...",
  "version": 1,
  "createdAt": "2026-04-18T12:34:56.000Z"
}

ENCRYPT_STORE=true の場合、ファイルの内容は暗号化され、プレーンテキストの JSON ではなく base64 暗号文として保存されます。

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

• MCP のレスポンスを通じて秘密鍵がサーバーの外部に出ることはありません
• キーファイルは 0600 の権限で書き込まれます
• 保存時の暗号化はオプションですが、一時的なローカル開発以外では推奨されます
• HTTP モード自体では認証も TLS も追加されません。信頼できるローカル境界の内側に配置するか、独自のリバース プロキシの背後に配置してください
• keyId の値はファイル名になるため、安定していてファイルシステムで安全に使用できる ID を使ってください

開発

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm format:check

ビルド後にローカルで実行します。

pnpm start

開発中にビルド済みの出力を監視します。

pnpm start:dev

新しいアルゴリズムの追加

1. KeyAlgorithmAdapter を拡張して、新しいアダプターを実装します
2. src/keystore/index.ts に登録します
3. ユーザーが選択できるようにする場合は、該当するツールスキーマを通じてアダプター名を公開します

import { KeyAlgorithmAdapter } from '../adapter.js';
import type { KeyPair } from '../types.js';

export class MyAdapter extends KeyAlgorithmAdapter {
  readonly name = 'my-algo';

  generate(): KeyPair {
    /* ... */
  }

  sign(privateKey: string, data: Buffer): string {
    /* ... */
  }

  verify(publicKey: string, data: Buffer, signature: string): boolean {
    /* ... */
  }

  rotate(_currentKeyPair: KeyPair): KeyPair {
    return this.generate();
  }
}

プロジェクト構成

src/
  config/               environment parsing and validation
  keystore/             adapters, registry, and file-based storage
  tools/                MCP tool registration and handlers
  utils/                crypto helpers, errors, serializers
  server.ts             MCP server construction
  main.ts               stdio and HTTP entry point
test/                   unit tests

ライセンス

MIT