Content
# local-kms-mcp-server
[](https://badge.fury.io/js/local-kms-mcp-server)
[](LICENSE)
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.
```json
{
"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.
```bash
TRANSPORT=http PORT=8080 npx local-kms-mcp-server
```
Endpoint:
```text
POST http://localhost:8080/mcp
```
## Installation
Run directly with `npx`:
```bash
npx -y local-kms-mcp-server
```
Or install globally:
```bash
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:
```bash
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:
```json
{
"keyId": "key-1",
"message": "eyJub25jZSI6IjEyMyJ9"
}
```
## Storage Model
Unencrypted keys are stored as one file per key under `${STORE_PATH}`:
```text
${STORE_PATH}/${keyId}.json
```
Stored records contain:
```json
{
"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
```bash
pnpm install
pnpm build
pnpm test
pnpm lint
pnpm format:check
```
Run locally after building:
```bash
pnpm start
```
Watch the built output during development:
```bash
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
```typescript
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
```text
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
