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.

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.

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 vtimestamp-mcp-write@1.2.0+) — 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 vtimestamp-mcp-write@1.1.x and earlier) — per-field DataDescriptors (sha256, title, description, filename, filesize) under labeled keys. Read directly without decryptdata.

The reader b

... View full README on GitHub