Local Kms Mcp

local-kms-mcp-server

本地优先、轻量级的 MCP 服务，用于为每个 Agent 管理密钥。

为每个 Agent 提供独立的签名身份，无需依赖外部 KMS，也无需暴露私钥。

local-kms-mcp-server 可完全在本地计算机上生成、存储、轮换并使用签名密钥对。密钥永远不会离开进程，不会接触网络，并始终由你掌控。

它面向需要隔离且可组合身份的 MCP 客户端和 Agent 运行时，可用于 DID/SSI 流程、身份验证握手、挑战签名，以及任何需要 Agent 以加密方式证明某些内容的工作流。

功能

• 生成绑定到 keyId 的签名密钥对（每个 Agent 或任务对应一个身份）
• 使用简单的基于文件的密钥库在本地存储密钥
• 对 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. 调用 generate_key 为新的 keyId 生成密钥
3. 调用 get_key_info 获取公钥，用于注册或分发
4. 每当 Agent 需要对质询或负载签名时，调用 sign_message
5. 需要为同一 keyId 生成新的密钥材料时，调用 rotate_key
6. 不再需要密钥对时，调用 delete_key 安全地将其删除
7. 调用 check_keypair 或 list_keys 检查密钥清单和存在状态

sign_message 负载示例：

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

存储模型

未加密的密钥以每个密钥一个文件的形式存储在 ${STORE_PATH} 下：

${STORE_PATH}/${keyId}.json

已存储的记录包含：

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

当 ENCRYPT_STORE=true 时，文件内容会被加密，并以 base64 密文而非明文 JSON 的形式持久化。

安全说明

• 私钥不会通过 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