nostr-mcp-auth

Lock MCP tools to a Nostr key

No proof, no tools. Agents sign every HTTP call with a Nostr secret. The server checks the signature offline. Wrong key, bad sig, stale event, or body swap: 401. Tool code never runs.

pip install -e .
nostr-mcp-auth quickstart
nostr-mcp-auth serve
# other terminal:
nostr-mcp-auth call --tool whoami

Crypto identity for agent tool access. No OAuth dance required for the lab or fleet path.

What is Nostr?

Nostr is a simple open protocol for signed messages. Each user (or agent) has:

Messages (events) are JSON objects with a BIP-340 Schnorr signature. Anyone can verify who signed without a central account server.

Common uses: social apps, relays, Lightning wallet connect. The part we care about for MCP is pure crypto identity: prove key possession.

You do not need Damus, a public relay, or a social profile for this package. Verification is local.

NIP-98 (HTTP auth)

NIP-98 defines how to authorize an HTTP request with a short-lived signed event:

• Kind 27235

• Tags bind the request: URL (u), method (method), optional body hash (payload)

• Header: Authorization: Nostr <base64-encoded event>

That is the protocol. This repo turns it into a gate in front of MCP tools.

Related MCP server: Agent Identity MCP Server

How we use Nostr for MCP

MCP (Model Context Protocol) is how agents call tools over stdio or HTTP. Network MCP needs auth. We put NIP-98 on POST /mcp.

Agent / sidecar                         MCP server (this package)
     |                                          |
     |  POST /mcp                               |
     |  Authorization: Nostr <signed event>     |
     |  tools/call { name, arguments }          |
     |----------------------------------------->|
     |                                          |  verify NIP-98 (offline)
     |                                          |  allowlist + roles
     |                                          |  run tool  OR  401/403
     |<-----------------------------------------|

What we take from Nostr

• Keypair identity (npub / nsec)

• Event shape + Schnorr signatures

• NIP-98 request binding

What we do not need

• Public relays for auth

• Social graph, follows, or notes

• Publishing the auth event anywhere

What we add

• Fail-closed HTTP MCP surface (tools/list, tools/call)

• Allow / deny lists and optional tool roles

• Process-local replay defense

• Operator CLI: quickstart, serve, call, doctor

• Red-team tested gate (see docs/)

Plug in

Install

git clone https://github.com/SamsonCyber/nostr-mcp-auth.git
cd nostr-mcp-auth
pip install -e .

Bootstrap

nostr-mcp-auth quickstart

Serve

nostr-mcp-auth serve
# http://127.0.0.1:8787/mcp
# http://127.0.0.1:8787/health   (public)

serve refuses auth.open=true and auth.trust_proxy=true unless you pass --force-open or --force-trust-proxy (lab / reverse-proxy only).

Call

nostr-mcp-auth call --tool whoami
nostr-mcp-auth call --tool protected_echo --arg text=hello
nostr-mcp-auth list-tools
nostr-mcp-auth doctor

Python

from nostr_mcp_auth.client import call_tool

print(call_tool("http://127.0.0.1:8787/mcp", "caller.nsec", "whoami"))

See examples/python_agent.py.

Agent UIs that cannot sign (Claude Desktop, etc.)

Most hosts do not implement NIP-98. Options:

1. Local signing sidecar that holds nsec and forwards signed HTTP.

2. Keep high-risk tools on this HTTP gate; use stdio only where local trust is enough.

Unsigned or plain Bearer clients get 401. That is the gate doing its job.

Endpoints and demo tools

Wire real tools behind the same pattern, or terminate network MCP at this process.

Fail-closed checks

Defaults: open: false, trust_proxy: false. Auth logs never print nsec or full Authorization tokens. Multi-instance shared replay and stolen allowlisted nsec remain residual (see residual risks).

More: SPEC · residual risks · red-team · wave 2

Config

auth:
  open: false
  allow_npubs:
    - npub1...
  roles:
    npub1...: [tools:admin]
tools:
  admin_ping:
    roles: [tools:admin]
server:
  host: 127.0.0.1
  port: 8787

Add agents by generating keys and appending npubs. Example: examples/mcp-auth.example.yaml.

CLI

Dev

pip install -e ".[dev]"
pytest -q

Python 3.10+. Uses coincurve for BIP-340.

License

MIT