nostr-mcp

A read-only Model Context Protocol server for exploring Nostr safely. It gives agents semantic tools for resolving Nostr identifiers, reading profiles and events, querying notes, and inspecting relay metadata.

This first release deliberately does not accept private keys or publish events. Signing will be added through a remote signer such as NIP-46, with explicit user approval boundaries.

Tools

Tool	Purpose
nostr_resolve_identity	Decode hex, npub, nprofile, note, nevent, and naddr identifiers
nostr_get_profile	Fetch the newest valid kind 0 profile for a pubkey
nostr_get_event	Fetch one event by hex ID, note, or nevent
nostr_query_notes	Query verified kind 1 notes with bounded filters
nostr_inspect_relay	Fetch and normalize a relay's NIP-11 information document

Every returned event includes the relays that supplied it. Invalid signatures are discarded, duplicate events are merged, and partial relay failures are reported rather than hidden.

Requirements

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

Install for Codex

Install and register the server with one command:

npx -y @diegoyegros/nostr-mcp install

Verify the registration:

npx -y @diegoyegros/nostr-mcp doctor
codex mcp list

The installer stores this stdio command in Codex:

npx -y @diegoyegros/nostr-mcp@latest

Remove the registration with:

npx -y @diegoyegros/nostr-mcp uninstall

Install as a Codex plugin

The repository is also a Codex plugin marketplace containing the MCP server and a bundled Nostr skill:

codex plugin marketplace add DiegoYegros/nostr-mcp --ref master

Open Codex, run /plugins, select Nostr Plugins, and install Nostr MCP. The plugin is read-only and adds guidance for resolving identifiers, querying public notes, inspecting events, and reporting relay provenance.

The direct MCP installer and plugin installation are alternatives. Installing the plugin already provides its bundled MCP server.

Run with any MCP client

After the npm package is published, any stdio-compatible MCP host can launch it with:

npx -y @diegoyegros/nostr-mcp@latest

Example MCP client configuration:

{
  "mcpServers": {
    "nostr": {
      "command": "npx",
      "args": ["-y", "@diegoyegros/nostr-mcp@latest"],
      "env": {
        "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol"
      }
    }
  }
}

Run from source

npm install
npm run build
node dist/index.js

Register a source checkout with Codex:

codex mcp add nostr -- "$(command -v node)" "$PWD/dist/index.js"

Configuration

Variable	Default	Meaning
NOSTR_RELAYS	wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net	Comma-separated default relay URLs
NOSTR_QUERY_TIMEOUT_MS	5000	Per-query timeout, clamped to 500-30000 ms
NOSTR_MAX_RELAYS	8	Maximum relays per tool call, clamped to 1-20

Only public wss:// relay URLs are accepted by default. URLs containing credentials, fragments, loopback hosts, or private-network IP addresses are rejected.

When a tool call supplies relay_urls, only those relays are queried. Otherwise, safe relay hints from NIP-19 identifiers are tried before the configured defaults.

Development

npm run check

The checks include type checking, 54 unit and integration tests, a modern MCP stdio negotiation smoke test, the installer CLI, plugin metadata consistency, and npm package contents. Relay tests use fake relays and signed fixtures, so they are deterministic and do not depend on public relay availability.

Preview the npm artifact without publishing it:

npm pack --dry-run

Publishing

The npm name is @diegoyegros/nostr-mcp. A manual first release can be published with:

npm login
npm publish --access public

The included prepublishOnly hook runs the full verification suite before publishing. Later releases can be automated by creating a GitHub release after configuring the repository's NPM_TOKEN secret. The release workflow publishes the package with npm provenance.

Security model

• Read-only MCP tool annotations
• No nsec or raw private-key inputs
• Signature verification before events reach the agent
• Strict relay URL validation to reduce SSRF risk
• Bounded relay counts, result sizes, and timeouts
• Relay provenance and per-relay errors in query results

See SECURITY.md for reporting and trust-boundary details.

License

MIT