Nostr Read

A small, read-only Nostr MCP 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, 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.

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):

"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.