# nostr-read-mcp

A small, **read-only** [Nostr](https://nostr.com) [MCP](https://modelcontextprotocol.io)
server for local AI agents (Claude Code and any other MCP client). It lets your agent
**read** the Nostr network — profiles, notes, full-text search, and relay lists — through
relays you choose. No account, no keys, no third-party API.

Built on [`nostr-tools`](https://github.com/nbd-wtf/nostr-tools), Bun-native, ~210 lines.

## Read-only by construction

There is **no signing, publishing, zapping, DM, or private-key code** in this server. It
cannot write to Nostr and reads no secrets — so there's nothing to leak and no deny-list to
maintain. The only configuration is which relays to read from.

## Tools

| Tool | What it does |
|------|--------------|
| `nostr_get_profile` | Kind-0 metadata (name, nip05, lud16, about) for a pubkey |
| `nostr_get_notes` | Recent notes (kind 1 by default) for a pubkey, newest first |
| `nostr_query` | Generic filter — authors, kinds, ids, tags (`#e`/`#p`/`#t`), since/until, limit |
| `nostr_search` | NIP-50 full-text search across search-capable relays |
| `nostr_get_relay_list` | NIP-65 (kind 10002) read/write relays for a pubkey |
| `nostr_nip19` | Decode/encode `npub`/`nprofile`/`note`/`nevent` (pure local, no network) |

Pubkeys may be given as hex, `npub…`, or `nprofile…`.

## Install

Requires [Bun](https://bun.sh).

```sh
git clone <this-repo> nostr-read-mcp
cd nostr-read-mcp
bun install
```

## Register with an MCP client

Add to your client's MCP server config. For Claude Code (`~/.claude.json` → `mcpServers`):

```json
"nostr": {
  "command": "bun",
  "args": ["/path/to/nostr-read-mcp/index.ts"],
  "env": {}
}
```

Then restart the client so it loads the server.

## Configuration (optional env)

| Var | Default | Purpose |
|-----|---------|---------|
| `NOSTR_RELAYS` | damus, nostr.band, nos.lol, primal, purplepag.es | Comma-separated read relays |
| `NOSTR_SEARCH_RELAYS` | search.nos.today, relay.nostr.band, relay.noswhere.com | NIP-50 search relays |
| `NOSTR_TIMEOUT_MS` | `8000` | Per-query timeout |

Multiple search relays are configured for redundancy — any single one is often down, and the
pool aggregates across whichever answer.

## License

MIT — see [LICENSE](./LICENSE).