vtimestamp-mcp

MCP server for verifying and querying vtimestamp proofs on the Verus blockchain.

Enables AI agents (Claude Desktop, VS Code, etc.) to verify document timestamps and list all timestamps on a VerusID — directly from the blockchain.

Looking for the write server? See vtimestamp-mcp-write — needs a local daemon and a wallet with the identity's private key.

Installation

Claude Code

claude mcp add --transport stdio --scope user vtimestamp-read -- npx vtimestamp-mcp@latest

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vtimestamp": {
      "command": "npx",
      "args": ["-y", "vtimestamp-mcp@latest"]
    }
  }
}

Using yarn:

{
  "mcpServers": {
    "vtimestamp": {
      "command": "yarn",
      "args": ["dlx", "vtimestamp-mcp"]
    }
  }
}

Using pnpm:

{
  "mcpServers": {
    "vtimestamp": {
      "command": "pnpm",
      "args": ["dlx", "vtimestamp-mcp"]
    }
  }
}

VS Code

Add to your VS Code MCP settings:

{
  "mcp": {
    "servers": {
      "vtimestamp": {
        "command": "npx",
        "args": ["-y", "vtimestamp-mcp@latest"]
      }
    }
  }
}

Tools

vtimestamp_verify

Verify whether a file or text has been timestamped on a VerusID. Provide either a file path or text — the server computes the SHA-256 hash and checks it against the on-chain record.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | identity | string | Yes | VerusID name (e.g., alice@) | | file_path | string | One of | Path to a file to verify | | text | string | One of | Text string to verify |

Either file_path or text must be provided (mutually exclusive).

Example prompts:

• "Check if the file at /path/to/report.pdf has been timestamped on alice@"
• "Verify this text was timestamped on bob@: I attest that invoice #4521 was approved"

vtimestamp_list

List all timestamps recorded on a VerusID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | identity | string | Yes | VerusID name (e.g., alice@) |

Example: "What documents has alice@ timestamped?"

vtimestamp_info

Get information about the vtimestamp service.

No parameters.

Example: "What is vtimestamp?"

How It Works

By default, the server queries a public Verus mainnet RPC endpoint. No wallet, no API keys, no authentication required.

AI Agent (Claude Desktop, VS Code, etc.)
    │ stdio (JSON-RPC)
    ▼
vtimestamp-mcp (local)
    │ HTTPS (JSON-RPC 1.0)
    ▼
Public Verus Mainnet RPC (rpc.vrsc.syncproof.net, fallback api.verus.services)

You can also point this server at your own daemon — useful for testnet (where no public RPC supports decryption), high-volume agents, custom chains, or anyone who'd rather not have their inspections hit a public RPC. See Configuration below.

On-chain storage shape

vtimestamps are stored under a VerusID's contentmultimap and read via getidentityhistory (one history entry per updateidentity). This server handles two on-chain shapes transparently:

• Public-encrypted (flags: 13, written by [email protected]+) — the daemon's {data:{}} envelope produces a single ciphertext DataDescriptor with epk and ivk published on-chain. Reading these requires decryptdata + the originating txid + retrieve: true. Because the IVK is on-chain (public-encrypted mode), anyone can decrypt — no key sharing.
• Legacy plaintext (flags: 0, written by [email protected] and earlier) — per-field DataDescriptors (sha256, title, description, filename, filesize) under labeled keys. Read directly without decryptdata.

The reader branches on each entry's flags. Mixed identities (legacy entries from older writes alongside new encrypted entries) are handled correctly — both surface in vtimestamp_list output.

For background, see How to Publish Encrypted Data on an Identity.

Public RPC requirement

decryptdata is a daemon RPC method that public Verus RPCs do not all whitelist. As of writing:

| Endpoint | Chain | decryptdata | Notes | |---|---|---|---| | https://rpc.vrsc.syncproof.net | VRSC mainnet | ✅ enabled | This server's primary endpoint. | | https://api.verus.services | VRSC mainnet | ❌ disabled | Fallback only. Encrypted entries fail to decrypt here, but legacy plaintext reads still work. | | https://api.verustest.net | VRSCTEST | ❌ disabled | No public testnet RPC supports decryptdata. Testnet encrypted reads require a local daemon. |

If syncproof is unreachable and the call falls back to api.verus.services, encrypted entries will gracefully surface as un-decryptable rather than crashing.

Configuration

For default public-RPC use, no configuration is needed. To point the server at your own daemon (required for testnet, recommended for high-volume use), set environment variables.

Environment Variables

All optional. Setting any of these switches the server from public-RPC mode to local-daemon mode.

| Variable | Description | |----------|-------------| | VERUS_RPC_URL | Daemon RPC URL (e.g., http://127.0.0.1:27486 for mainnet, http://127.0.0.1:18843 for testnet) | | VERUS_CONF_PATH | Path to a VRSC.conf / vrsctest.conf file. Auto-derives URL (http://127.0.0.1:<rpcport>) and credentials. | | VERUS_RPC_USER | Override: RPC username | | VERUS_RPC_PASSWORD | Override: RPC password |

Behavior:

• (no env vars) → public RPC pair (rpc.vrsc.syncproof.net primary, api.verus.services fallback). Mainnet only.
• VERUS_RPC_URL set → single local endpoint at that URL. Auth from VERUS_RPC_USER + VERUS_RPC_PASSWORD, or auto-derived from VERUS_CONF_PATH if those are missing.
• VERUS_CONF_PATH set (without VERUS_RPC_URL) → URL = http://127.0.0.1:<rpcport> from the conf, with credentials from the conf.

Local daemon example (testnet)

{
  "mcpServers": {
    "vtimestamp": {
      "command": "npx",
      "args": ["-y", "vtimestamp-mcp@latest"],
      "env": {
        "VERUS_CONF_PATH": "/Users/you/Library/Application Support/Komodo/vrsctest/vrsctest.conf"
      }
    }
  }
}

Or pin everything explicitly:

{
  "mcpServers": {
    "vtimestamp": {
      "command": "npx",
      "args": ["-y", "vtimestamp-mcp@latest"],
      "env": {
        "VERUS_RPC_URL": "http://127.0.0.1:18843",
        "VERUS_RPC_USER": "rpc-user-from-conf",
        "VERUS_RPC_PASSWORD": "rpc-password-from-conf"
      }
    }
  }
}

Requirements

• Node.js 18+
• For default operation: nothing else — uses public mainnet RPC.
• For testnet or local-daemon mode: a running verusd (or verusd -chain=vrsctest) on the host you point at.

License

MIT