Use relay intelligence via MCP over Nostr (CVM)

CVM (ContextVM) is MCP (Model Context Protocol) running over Nostr relays instead of HTTP. It exposes 21 structured tools for querying NIP-66 relay monitoring data. Your client sends a tool call as a Nostr event; the rstate server processes it and returns the result as another Nostr event. No IP addresses are exposed, no API keys are needed, and the entire stack is self-hostable.

How MCP over Nostr works

Standard MCP runs over HTTP. CVM replaces the HTTP transport with Nostr relay transport:

Your client connects to one or more CVM relay(s) using a Nostr keypair
The client sends a tool call as a signed Nostr event addressed to the server’s pubkey
The rstate server receives the event, processes the tool call, and publishes the response as a Nostr event
Your client receives the response event and extracts the tool output

The result is a fully functional MCP server accessible over the Nostr network. Communication is identified by Nostr pubkeys rather than IP addresses, which means no client IP is exposed to the server.

Getting started with Claude Desktop

The fastest way to use CVM is through Claude Desktop. Add the following to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "relayvm": {
      "command": "npx",
      "args": ["-y", "@nostr-watch/relayvm"],
      "env": {
        "CVM_RELAYS": "wss://relay.damus.io,wss://relay.nostr.band",
        "INGEST_RELAYS": "wss://history.nostr.watch",
        "CVM_SERVER_NSEC": "nsec1..."
      }
    }
  }
}

Once configured, Claude can answer natural language questions about relay data by calling the appropriate CVM tools automatically:

Find all relays that support NIP-42 authentication

List the top 10 most reliable relays by uptime

Show me relays within 100km of San Francisco

Compare relay.damus.io and relay.nostr.band

Find all relays running strfry software

Show me offline relays that were recently seen

Programmatic usage

You can call CVM tools directly from code using the CVM SDK, which handles the Nostr transport for you.

// The CVM SDK handles the Nostr transport
const result = await cvmClient.callTool('relays/list', {
  limit: 10,
  sortBy: 'updated',
  sortOrder: 'desc',
  format: 'detailed'
})

console.log(result.relays) // Array of relay state objects
console.log(result.total)  // Total relay count

Available tools

CVM provides 21 tools organized into eight groups:

Relay query tools

Tool	Description
`relays/list`	Get a paginated list of all relays. Supports `limit`, `offset`, `sortBy`, `sortOrder`, and `format`.
`relays/state`	Get state for a specific relay URL. Pass `relayUrl` (required) and `format`.
`relays/search`	Search relays by `network`, `nips`, `software`, `labels`, `maxLatency`, and `minSupport`.

Geospatial tools

Tool	Description
`relays/nearby`	Find relays near a geographic point. Pass `lat`, `lon`, `radius` (km), and `maxResults`. Each result includes a `distance` field in km.
`relays/bbox`	Find relays within a bounding box. Pass `sw` and `ne` as `{ lat, lon }` objects.

Label tools

Tool	Description
`relays/labels`	Get labels for a specific relay. Pass `relayUrl` and optional `namespace` filter.
`relays/labels/list`	List all available labels across all relays. Optional `namespace` filter.
`relays/by/label`	Get relays with a specific label. Pass `namespace` and `value` (both required).

Aggregation tools

Tool	Description
`relays/by/software`	Group relays by software family. Optional `family` filter.
`relays/by/network`	Group relays by network type (clearnet, Tor, I2P, hybrid).
`relays/by/nip`	Group relays by NIP support. Optional `nip` filter and `minSupport` threshold.
`relays/by/country`	Group relays by country. Optional `countryCode` filter (ISO 3166-1 alpha-2).

Availability tools

Tool	Description
`relays/online`	List relays considered online. Optional `onlineWindowSeconds`, `filters`, pagination.
`relays/offline`	List relays that are offline but not yet dead. Configurable `offlineThresholdSeconds`.
`relays/dead`	List relays not seen for a long time. Default threshold: 7 days.
`relays/compare`	Compare 2–10 relays side-by-side. Returns common NIPs, requirements, and differences.

Monitor tools

Tool	Description
`monitors/get`	Get information about a specific monitor by `pubkey`. Returns monitor data and reliability analytics.
`monitors/list`	List all known monitors with reliability scores, sorted by last seen.

System tools

Tool	Description
`health/ping`	Check server health, version, uptime, relay connection counts, and cache stats.
`policy/get`	Get current aggregation policy (quorum, labelQuorum, madScale, weights).
`policy/set`	Update aggregation policy (requires authorization).

Subscription tools

Tool	Description
`relays/subscribe_state`	Subscribe to relay state change notifications. Supports rich filters: relay URLs, network, NIPs, software, labels, geo area, and change thresholds.
`relays/unsubscribe`	Cancel a state change subscription by `subscriptionId`.

Response formats

All relay query tools accept a format parameter:

Format	Returns	Use when
`full`	All fields including per-monitor attribution	You need to see which monitors reported what
`detailed`	Aggregated values without attribution (default)	Most use cases
`simple`	Relay URLs only	You just need a list of addresses

Payments

CVM supports optional micro-payments via the CEP-8 pricing protocol. Most tools are free. When a CVM server has payment gating enabled:

The client calls a tool
The server returns a payment request with amount, currency, and payment method
The client pays via L402 (Lightning) or P2PK (Cashu)
The server processes the tool call after payment confirmation

The public nostr.watch CVM does not currently charge for basic queries. When self-hosting, you control pricing via a PRICING_YAML configuration file. Free tools do not need entries in the pricing file.

Only entries with amount > 0 in the pricing file activate payment gating. All other tools remain free regardless of whether a pricing file is present.

Self-hosting

Running your own rstate instance gives you full sovereignty — you ingest raw NIP-66 events directly from Nostr relays and no trust in nostr.watch is required. Prerequisites: Node.js >= 20 and a Nostr private key (nsec) for the server identity.

Clone and install

git clone https://github.com/sandwichfarm/nostr-watch.git
cd nostr-watch
pnpm install
cd apps/rstate

Configure

cp config.sample.yaml config.yaml

Edit config.yaml:

cvm:
  enabled: true
  relays:
    - 'wss://relay.damus.io'
    - 'wss://relay.nostr.band'
  encryptionMode: OPTIONAL
  allowedPubkeys: []  # empty = allow all clients

ingestRelays:
  - 'wss://history.nostr.watch'
  - 'wss://relay.nostr.watch'

rest:
  enabled: false  # set to true to also enable the REST API

aggregation:
  quorum: 0.5
  labelQuorum: 0.3
  madScale: 3.0

Build and start

npm run build
npm start

Verify

curl http://localhost:3000/health/ping | jq '.'

Look for status: "ok", relayCount.ingestion > 0, and observationCount > 0.

Environment variables (override YAML config values):

Variable	Required	Description
`CVM_RELAYS`	Yes	Comma-separated relay URLs for CVM transport
`INGEST_RELAYS`	Yes	Relay URLs for NIP-66 event ingestion
`CVM_SERVER_NSEC`	Yes	Server private key for signing responses
`REST_ENABLED`	No	Enable REST API alongside CVM
`REST_PORT`	No	REST API port (default: 3000)
`LOG_LEVEL`	No	Logging verbosity

Keep CVM_SERVER_NSEC private. It is the server’s identity key — compromise means someone can impersonate your instance. Use allowedPubkeys to restrict access if running a private instance.

Trust model

CVM operates on a verify-or-self-host model. When using the public nostr.watch CVM, you trust that the rstate instance is honestly aggregating NIP-66 data. The aggregation logic is open source, but you cannot independently verify the results without running your own instance. Self-hosting eliminates this trust requirement entirely.

Next steps

CVM tools reference

Full parameter schemas and output descriptions for all 21 tools.

REST API

Standard HTTP endpoints for relay intelligence without Nostr.

Raw NIP-66

Trustless event subscription directly from Nostr relays.

Overview

Compare all three interfaces and choose the right one.

Get Started

Core Libraries

Running Services

Consuming NIP-66 Data

Extending

Use relay intelligence via MCP over Nostr (CVM)

How MCP over Nostr works

Getting started with Claude Desktop

Programmatic usage

Available tools

Relay query tools

Geospatial tools

Label tools

Aggregation tools

Availability tools

Monitor tools

System tools

Subscription tools

Response formats

Payments

Self-hosting

Trust model

Next steps

CVM tools reference

REST API

Raw NIP-66

Overview

Build docs developers (and LLMs) love

Get Started

Core Libraries

Running Services

Consuming NIP-66 Data

Extending

Documentation Index

​How MCP over Nostr works

​Getting started with Claude Desktop

​Programmatic usage

​Available tools

​Relay query tools

​Geospatial tools

​Label tools

​Aggregation tools

​Availability tools

​Monitor tools

​System tools

​Subscription tools

​Response formats

​Payments

​Self-hosting

​Trust model

​Next steps

CVM tools reference

REST API

Raw NIP-66

Overview

Build docs developers (and LLMs) love

How MCP over Nostr works

Getting started with Claude Desktop

Programmatic usage

Available tools

Relay query tools

Geospatial tools

Label tools

Aggregation tools

Availability tools

Monitor tools

System tools

Subscription tools

Response formats

Payments

Self-hosting

Trust model

Next steps