nostr-read-mcp

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.