nockchain-mcp

nockchain-mcp

An MCP server that gives an agent read access to Nockchain.

Built by Prism. Not affiliated with, endorsed by, or operated by Nockchain, Nock Community Co, Zorp, or National Compute.

Configure

{
  "mcpServers": {
    "nockchain": {
      "command": "npx",
      "args": ["-y", "nockchain-mcp"]
    }
  }
}

The server speaks stdio and needs Node 20 or newer. There is no API key to supply, because the public Nockchain API has none.

Tools

tool	arguments	answers
nock_tip	none	current height, with a freshness reading per endpoint
nock_balance	address	what the address can spend right now
nock_verify_payment	address, minNock or minNicks, optional sinceHeight, sinceTime, confirmations	whether the address has been paid
nock_block	block (height or block ID)	block contents
nock_transaction	txId	transaction contents, or the fallback below
nock_metrics	none	cache and refresh state of the selected endpoint, and its peer table
nock_endpoints	none	the full endpoint health table

Every tool is annotated read-only. The server never sends a transaction and holds no key.

Settings

variable	effect
NOCKCHAIN_ENDPOINTS	replaces the default pool. Comma-separated host:port, optionally prefixed tls:// or plain://. Port 443 defaults to TLS.
NOCKCHAIN_MAX_STALENESS_SECONDS	freshness cutoff for an endpoint. Defaults to 900.
NOCKCHAIN_MAX_HEIGHT_LAG	how far an endpoint may trail the best height in the pool. Defaults to 3.

What the answers mean

A balance is the set of unspent notes an address holds at the current tip. A spent note leaves that set, so the figure says what the address can spend now and says nothing about what it has received in the past. Payments carry no memo or tag on the wire, so correlate them by issuing one address per invoice.

A mining address can hold thousands of unspent notes, which is more JSON than a host will read. The totals always come back whole. A note list past the result budget is shortened instead, and what remains reports how many entries there really were.

nock_transaction handles a known upstream failure. The node cannot decode transactions produced after the Logos upgrade, and in that case the tool returns reason: "upstream_decoder_bug" along with the inclusion facts that are still available, such as the block height and its timestamp.

Sending NOCK is out of scope. That needs the official nockchain-wallet CLI.

Embedding

The package also exports createServer(client), which takes any read-only Nockchain client and returns a configured McpServer. Useful when the server needs to live inside a host process you already run.

The package is ESM. A CommonJS host reaches it with await import("nockchain-mcp").

License

Apache-2.0. Background and measurements are in the repository README.