# nostr-mcp

A Model Context Protocol server for Nostr. Agents can read verified public data and act on Nostr: post notes and replies, react, repost, publish articles, manage drafts, send encrypted direct messages, upload media, and send Lightning zaps. Private keys stay out of the conversation because signing happens inside the server process.

Reads report relay provenance. Invalid signatures are discarded, duplicate events are merged, and partial relay failures show up in results instead of being hidden.

## Quick start

```bash
# Register with Codex (or point any MCP host at the stdio command below)
npx -y @diegoaly_/nostr-mcp@latest install

# Create an encrypted identity (NIP-49 key file, passphrase prompted)
npx -y @diegoaly_/nostr-mcp@latest key generate
```

```jsonc
// Any MCP host. Signing activates when NOSTR_KEY_PASSPHRASE is present.
{
  "mcpServers": {
    "nostr": {
      "command": "npx",
      "args": ["-y", "@diegoaly_/nostr-mcp@latest"],
      "env": { "NOSTR_KEY_PASSPHRASE": "{your-passphrase}" }
    }
  }
}
```

With no identity configured the server runs read-only, and every write tool explains how to enable itself when called. If you would rather not hold keys locally at all, use a NIP-46 bunker: set `NOSTR_BUNKER_URI=bunker://...` from [Amber](https://github.com/greenart7c3/Amber) on Android, and the key never touches this machine.

## What it can do

**Read & discover.** Resolve any identifier (`npub`, `note`, `nevent`, `naddr`, NIP-05 handles), fetch profiles and events with relay provenance, reconstruct full threads, run full-text search over NIP-50 relays, look up NIP-65 relay lists, inspect NIP-11 relay documents.

**Publish.** Notes with automatic reply threading, reactions, reposts, deletes that check ownership first, profile editing that preserves unknown fields, and long-form markdown articles where republishing a slug edits the article.

**Drafts, DMs, media, money.** Encrypted local drafts. Sealed-sender private messages over NIP-17. Blossom media uploads that return ready-made imeta tags. Lightning zaps through Nostr Wallet Connect, capped by a server-side spend limit.

The complete tool reference lives in [`docs/tools.md`](docs/tools.md), and the protocol coverage matrix in [`docs/nips.md`](docs/nips.md).

## Identity options

| Option | Setup | Key location |
| --- | --- | --- |
| Encrypted key file *(recommended)* | `key generate` + `NOSTR_KEY_PASSPHRASE` | This machine, NIP-49-encrypted |
| Remote signer / Amber (NIP-46) | `NOSTR_BUNKER_URI=bunker://...` | Off-machine; signer approves each request |
| Raw env var *(automation only)* | `NOSTR_NSEC=nsec1...` | Process environment |

Zaps additionally need a wallet URI (`NOSTR_WALLET_NWC`, from Alby/Primal/Coinos). Per-zap spending is capped by `NOSTR_MAX_ZAP_MSAT` regardless of what an agent tries.

Full details in [`docs/configuration.md`](docs/configuration.md).

## Documentation

| Doc | Contents |
| --- | --- |
| [`docs/tools.md`](docs/tools.md) | All 31 tools: inputs, outputs, capability gating |
| [`docs/nips.md`](docs/nips.md) | Supported NIPs: implemented, internal, excluded |
| [`docs/configuration.md`](docs/configuration.md) | Every environment variable, identity setup, wallet setup |
| [`docs/architecture.md`](docs/architecture.md) | Layer structure, key interfaces, read/publish pipelines, secret handling |
| [`docs/development.md`](docs/development.md) | Dev workflow, testing principles, releasing |
| [`SECURITY.md`](SECURITY.md) | Trust boundaries and vulnerability reporting |

## Requirements

- Node.js 20.19 or newer
- An MCP host that supports stdio servers

## Development

```bash
npm run check
```

Type checking, the offline test suite, build, a real-stdio smoke test, and npm package validation. See [`docs/development.md`](docs/development.md).

## Security model

- Signing happens inside the server process; keys never appear in tool inputs, outputs, or logs
- NIP-49 encrypted keys at rest; NIP-46 bunker mode keeps keys off the machine entirely
- Server-enforced zap spend cap; destructive tools are annotated and gated behind explicit configuration
- Signature verification before events reach the agent; strict relay URL validation against SSRF
- Bounded relay counts, result sizes, and timeouts; per-relay errors reported, never swallowed

## License

MIT