# nockchain-mcp

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/mizuki0x/nockchain-agent  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/nockchain-mcp

## Description
Community-built read-only Nockchain access: balances, payment verification, blocks, node health.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation & README

# nockchain-agent

A typed TypeScript client and an MCP server for reading Nockchain from an agent.

This is a community project. It is not affiliated with, endorsed by, or operated by Nockchain, Nock Community Co, Zorp, or National Compute.

## Install

```sh
npm install nockchain-agent-sdk
```

The MCP server runs straight from npm:

```sh
npx nockchain-mcp
```

Node 20 or newer.

## Read a balance

```js
import { NockchainClient } from "nockchain-agent-sdk";

const client = new NockchainClient();
const balance = await client.getBalance("2s3K...");

console.log(`${balance.nock} NOCK (${balance.nicks} nicks) across ${balance.notes.length} notes`);
```

## Verify a payment

Issue one address per invoice, then ask whether it has been paid:

```js
import { NockchainClient } from "nockchain-agent-sdk";

const client = new NockchainClient();
const result = await client.verifyPayment({
  address: invoiceAddress,
  minNock: "1.5",
  sinceHeight: 133400,
  confirmations: 3,
});

if (result.paid) {
  console.log(`${result.confirmedNock} NOCK settled at height ${result.tipHeight}`);
}
```

## Use it from an MCP client

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

Seven tools, all read-only:

| tool | what it answers |
| --- | --- |
| `nock_tip` | current height, with a freshness reading per endpoint |
| `nock_balance` | what an address can spend right now |
| `nock_verify_payment` | has this address been paid, with confirmations |
| `nock_block` | block contents by height or block ID |
| `nock_transaction` | transaction contents, or why the node could not decode them |
| `nock_metrics` | cache and refresh state of the selected endpoint, and its peer table |
| `nock_endpoints` | the full endpoint health table |

## Why this exists

Two things about reading Nockchain today cost more time than they should.

**Balances come back as zero.** The public `WalletGetBalance` call accepts an address selector, and for notes in the current v1 format that selector returns nothing at all. The balance lives under the note first-name, which you reach by hashing the pay-to-pubkey-hash behind the address. Two derivations matter, because coinbase notes lock differently from ordinary ones, and the real balance is the union of both. `getBalance` does that work and returns the figure the address can actually spend.

**Public nodes go stale quietly.** Three endpoints, measured within the same minute on 2026-08-25:

| endpoint | height | age of its chain state |
| --- | --- | --- |
| `api.nockscan.net:443` | 133598 | 157 s |
| `23.252.122.18:5556` | 133598 | 214 s |
| `rpc.nockbox.org:443` | 133226 | 50625 s, close to 14 hours |

A response carries no sign of which of these answered it. The client probes every endpoint in its pool and declines to read from one that fails the freshness threshold, raising a typed error that names the ages it measured. `client.health()` returns the whole table.

## Limitations

**Read-only.** No signing library for Nockchain exists, so sending NOCK needs the official `nockchain-wallet` CLI. The SDK will submit a transaction the CLI has already produced. It will not build or sign one.

**A balance is the live unspent-note set.** It answers what an address can spend at the current tip. A spent note leaves the set, so the total is no record of what an address has received over its lifetime. Nothing the wallet sends carries a memo or a tag on the wire either, which is why payment correlation works by issuing one address per invoice.

**Upstream `GetTransactionDetails` fails on transactions produced after the Logos upgrade.** The node answers with a decoder error instead of the transaction. `getTransactionDetails` catches that case and returns `{ ok: false, reason: "upstream_decoder_bug", txId, fallback }`, where `fallback` carries the inclusion facts that `GetTransactionBlock` and `GetBlockDetails` could still establish, such as the block height and its timestamp.

**The public API is alpha and unauthenticated.** There is no key to obtain and no rate limit to plan against. Endpoints move and lag without notice.

## Packages

| package | contents |
| --- | --- |
| [`nockchain-agent-sdk`](https://github.com/mizuki0x/nockchain-agent/blob/HEAD/packages/sdk) | the client and the note first-name derivation it depends on |
| [`nockchain-mcp`](https://github.com/mizuki0x/nockchain-agent/blob/HEAD/packages/mcp) | the stdio MCP server built on it |

## Examples

The examples import the workspace build, so build it once first.

```sh
npm install
npm run build
node examples/balance.mjs 2s3K...
node examples/verify-payment.mjs 2s3K... 1.5
```

Both read the public network.

## Development

```sh
npm install
npm run build
npm test
```

Tests run offline against fixtures, including the golden vectors generated from the upstream Rust crates. Nothing in the test suite opens a socket.

## License

Apache-2.0. See [LICENSE](https://github.com/mizuki0x/nockchain-agent/blob/HEAD/LICENSE) and [NOTICE](https://github.com/mizuki0x/nockchain-agent/blob/HEAD/NOTICE).