Local Kms Server

npm version License: MIT

Local-first, lightweight MCP server for per-agent key management.

Give every agent its own signing identity - without relying on external KMS or exposing private keys.

local-kms-mcp-server generates, stores, rotates, and uses signing keypairs entirely on the local machine. Keys never leave the process, never touch the network, and stay under control.

It’s built for MCP clients and agent runtimes that need isolated, composable identities for tasks such as DID/SSI flows, auth handshakes, challenge signing, and any workflow where agents must prove something cryptographically

What It Does

• Generates signing keypairs scoped to a keyId (one identity per agent or task)
• Stores keys locally using a simple file-based keystore
• Rotates keys safely while preserving algorithm consistency
• Signs base64 payloads without ever exposing private key material
• Optionally encrypts keys at rest using AES-256-GCM
• Runs over MCP via stdio (default) or HTTP when needed

Supported Algorithms

Algorithm	Tool value	Notes
Ed25519	ed25519	Good default for general signing and DID-style use cases
ECDSA secp256k1	ecdsa-secp256k1	Common for Ethereum, Bitcoin, and other Web3 flows
ECDSA P-256	ecdsa-prime256v1	ES256, WebAuthn, and common cloud KMS compatibility
ECDSA P-384	ecdsa-secp384r1	Higher-security NIST P-384 environments

Requirements

• Node.js >=24.0.0
• An MCP client that supports stdio or HTTP MCP servers

Quick Start

Stdio transport

Use stdio when running from Claude Desktop, Cursor, or another local MCP client.

{
  "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 transport

Use HTTP only when you explicitly want a local network endpoint.

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

Endpoint:

POST http://localhost:8080/mcp

Installation

Run directly with npx:

npx -y local-kms-mcp-server

Or install globally:

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

Configuration

Environment variable	Default	Description
STORE_PATH	./keys	Directory used for persisted key files
TRANSPORT	stdio	MCP transport: stdio or http
PORT	8080	HTTP port used only when TRANSPORT=http
ENCRYPT_STORE	false	Set to true or 1 to encrypt key files at rest
STORE_ENCRYPTION_KEY	none	Base64-encoded 32-byte key required when encryption is enabled

For local development there is an example file at .env.example, but for actual MCP client usage it is better to pass values through the client's env configuration so startup is deterministic.

Generate an encryption key:

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

Tool Reference

All tool inputs are validated with Zod. Public keys and signatures are returned as base64 strings.

Tool	Purpose	Input	Output
check_keypair	Check whether a key exists	{ "keyId": "agent-1" }	{ "exists": true }
list_keys	List all stored key IDs	{}	{ "keys": ["agent-1", "agent-2"] }
generate_key	Create and persist a new keypair	{ "keyId": "agent-1", "algo": "ed25519" }	{ "publicKey": "..." }
get_key_info	Return the stored public key for a key ID	{ "keyId": "agent-1" }	{ "publicKey": "..." }
rotate_key	Rotate an existing keypair using its stored algorithm	{ "keyId": "agent-1" }	{ "newPublicKey": "..." }
sign_message	Sign a base64-encoded payload	{ "keyId": "agent-1", "message": "aGVsbG8=" }	{ "signature": "..." }

Notes:

• generate_key fails if the keyId already exists
• rotate_key increments the stored version
• sign_message expects message to already be base64-encoded
• sign_message accepts an optional algo override, but in normal usage the stored algorithm is usually what you want

Typical Usage Flow

1. Call generate_key for a new keyId
2. Call get_key_info to retrieve the public key for registration or distribution
3. Call sign_message whenever the agent needs to sign a challenge or payload
4. Call rotate_key when you need new key material for the same keyId
5. Call check_keypair or list_keys for inventory and existence checks

Example sign_message payload:

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

Storage Model

Unencrypted keys are stored as one file per key under ${STORE_PATH}:

${STORE_PATH}/${keyId}.json

Stored records contain:

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

When ENCRYPT_STORE=true, the file contents are encrypted and persisted as base64 ciphertext instead of plaintext JSON.

Security Notes

• Private keys never leave the server through MCP responses
• Key files are written with 0600 permissions
• At-rest encryption is optional but recommended for anything beyond throwaway local development
• HTTP mode does not add authentication or TLS by itself; keep it behind a trusted local boundary or your own reverse proxy
• keyId values become filenames, so use stable, filesystem-safe IDs

Development

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

Run locally after building:

pnpm start

Watch the built output during development:

pnpm start:dev

Extending With New Algorithms

1. Implement a new adapter by extending KeyAlgorithmAdapter
2. Register it in src/keystore/index.ts
3. Expose the adapter name through the relevant tool schema if users should be able to select it

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();
  }
}

Project Layout

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

License

MIT