obyte-mcp

Local stdio MCP server for querying Obyte from AI tools. One server serves both mainnet and testnet — every tool takes an optional network, so you never run two servers.

obyte-mcp exposes Obyte hub reads, autonomous-agent inspection, AA dry runs, and token symbol helpers to MCP clients such as Cursor, VS Code, Codex, Claude Desktop, and Claude Code.

Quick Start

Use a button above, or run the one command for your client:

claude mcp add --transport stdio obyte -- npx -y obyte-mcp                    # Claude Code
codex mcp add obyte -- npx -y obyte-mcp                                       # Codex CLI
code --add-mcp '{"name":"obyte","command":"npx","args":["-y","obyte-mcp"]}'   # VS Code
npx -y obyte-mcp install                                                      # every client on this machine

Needs Node.js >=20. Nothing else to configure: no account, no API key, no per-network setup - mainnet and testnet are both served from the start. Restart your client afterwards and ask it something like "what is the GBYTE balance of this Obyte address?".

To make testnet the default for calls that omit network (both stay available), add --network testnet to any of the commands above.

Install (one command)

Registers the server with every MCP client it finds on this machine. It runs each client's own CLI (code --add-mcp, codex mcp add, claude mcp add) and writes the Cursor and Claude Desktop config files directly.

Clients that are not installed are skipped quietly - only what actually changed is reported, along with which clients to restart. Naming one explicitly with --client always does something: if that client is not detected, the exact manual steps are printed instead.

Preview first (changes nothing):

npx -y obyte-mcp install --dry-run

Install into every detected client:

npx -y obyte-mcp install

Target a single client, or set the default network:

npx -y obyte-mcp install --client vscode
npx -y obyte-mcp install --client claude-desktop --network testnet
npx -y obyte-mcp install --client codex --name obyte-testnet --network testnet

Flags: --client vscode|cursor|codex|claude-desktop|claude-code (default: every detected client), --name NAME (server name, default obyte), --dry-run, plus any config flag from the table below.

From a checkout you can use the wrapper scripts (they build first if needed):

./scripts/install.sh --dry-run          # macOS / Linux
pwsh ./scripts/install.ps1 --dry-run    # Windows

Prefer copy-paste? npx -y obyte-mcp setup prints ready snippets for all clients without changing anything (add --print-only --client <name> for one).

VS Code

obyte-mcp install --client vscode runs code --add-mcp for you. To do it by hand, add to .vscode/mcp.json (workspace) or your user settings.json under "mcp":

{
  "servers": {
    "obyte": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obyte-mcp"]
    }
  }
}

VS Code uses servers (not mcpServers) and requires "type": "stdio".

Cursor

Cursor has no MCP CLI, so obyte-mcp install --client cursor writes its config file directly (backing the old one up to *.bak and keeping your other servers). The button at the top does the same in one click. To do it by hand, edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project) and restart Cursor:

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

Codex CLI

obyte-mcp install --client codex runs codex mcp add. To do it by hand, add to ~/.codex/config.toml (Codex uses TOML, not JSON):

[mcp_servers.obyte]
command = "npx"
args = ["-y", "obyte-mcp"]

Claude Desktop

Claude Desktop has no CLI, so obyte-mcp install --client claude-desktop edits its config file directly (it backs up the existing file to *.bak and merges, keeping your other servers). To do it by hand, edit claude_desktop_config.json and restart Claude Desktop:

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

Config paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code

obyte-mcp install --client claude-code runs:

claude mcp add --transport stdio obyte -- npx -y obyte-mcp

The -- before npx is required. Without it, Claude Code can parse server flags such as --network as Claude Code flags. Useful commands: claude mcp list, claude mcp get obyte, and /mcp inside Claude Code.

One-click bundle (.mcpb) for Claude Desktop / Claude Code

Anthropic's MCP Bundle format (.mcpb, formerly .dxt) lets users install with a single click in Claude Desktop, Claude Code, and MCP for Windows (VS Code and Codex do not support .mcpb). This repo ships a manifest.json. Build a bundle with:

npm ci --omit=dev   # keep the bundle small (runtime deps only)
npm run bundle      # builds, then runs `mcpb pack` -> obyte-mcp.mcpb

Then open obyte-mcp.mcpb in Claude Desktop and click Install. The bundle exposes a "Default network" option and an optional testnet token registry in the install UI.

What This Is

• A local MCP server that talks over stdio only.
• A read/query/dry-run connector for Obyte mainnet and testnet at the same time.
• A toolset for balances, units, witnesses, AA state vars, AA getters, AA dry runs, token symbols, and agent-friendly summaries.

What This Is Not

• Not a wallet.
• Not a signer.
• Not a transaction broadcaster.
• Not a service that opens a local TCP port.
• Not a place to paste private keys, seed phrases, mnemonics, xprv values, passphrases, or other secrets.

The server uses stdio only. It does not start an HTTP server and does not listen on a local TCP port.

Requirements

• Node.js >=20
• npm / npx
• An MCP client that supports local stdio servers

Official Obyte docs:

• https://developer.obyte.org/
• https://developer.obyte.org/autonomous-agents

Choosing A Network

This is the headline feature: you do not pick a network when starting the server — you pick it per call.

• Every tool accepts an optional network argument: "mainnet" or "testnet".
• When a call omits network, the server uses the default network (mainnet unless you set --network testnet / OBYTE_NETWORK=testnet).
• The response meta.network and meta.hub always tell you which network actually answered.
• Ask your client things like "check this balance on testnet" or "dry-run this AA on mainnet" and it will pass the right network. If the network is ambiguous, tools are documented to ask you first.

Inspect the live configuration for both networks any time with obyte_get_network_info.

Amounts And Decimals

Raw hub data (balances, AA state vars, payment outputs, AA responses) carries amounts as integers in the asset's smallest units. The base asset has 9 decimals: 2500000000 bytes = 2.5 GBYTE. Agents that skip this step report wrong numbers, so the server enforces it in three ways:

• Composite tools convert for you. obyte_analyze_address, obyte_analyze_aa, and obyte_get_portfolio_summary return a totals_by_asset / balance_summary block with symbol, decimals, raw_total, and display_total (already divided by 10^decimals). Assets that cannot be resolved (e.g. no registry on testnet) are listed in unresolved_assets with display_total: null — never presented as converted.
• Server instructions and tool descriptions tell agents to never show raw integers and to resolve decimals via obyte_resolve_asset / obyte_get_decimals_by_symbol_or_asset first, and to convert user-facing amounts into smallest units when building AA triggers.
• Base aliases work without a registry: decimals for base/GBYTE/MBYTE/KBYTE/BYTE are answered locally, even on testnet with no registry configured.

Asset holders

obyte_get_asset_holders returns the top holders of any asset (by symbol or asset id), sorted by balance descending, with raw and display amounts plus total supply — up to 100 holders per call. The data comes from the Obyte explorer (a centralized convenience service, separate from the hub) and may lag the ledger slightly.

For a human-browsable view, asset tools also return explorer_asset_url: https://explorer.obyte.org/asset/<symbol|asset> (testnet: https://testnetexplorer.obyte.org/asset/<symbol|asset>). Note: amounts on explorer web pages are already in display units — only hub tool outputs need decimals conversion.

Making Agents Use It Automatically

You should not have to tell your agent to use this server. Two mechanisms make it proactive:

1. MCP server instructions. At initialize the server sends instructions that hosts (Claude Desktop, Claude Code, and others) inject into the agent's context: use obyte_* tools whenever the user mentions Obyte, GBYTE/bytes, autonomous agents, or pastes an Obyte identifier (addresses are 32-character base32 strings; unit hashes and asset ids are 44-character base64 strings usually ending in =), plus the network and decimals rules.
2. Trigger-rich tool descriptions. Each tool description states when to reach for it, so hosts that only surface descriptions still route correctly.

For hosts that ignore server instructions (or to make it extra reliable in a specific project), add a line to your project memory file — CLAUDE.md (Claude Code) or AGENTS.md (Codex):

For anything involving Obyte, GBYTE, bytes, autonomous agents (AAs), Obyte units/addresses,
or Obyte token symbols, use the obyte MCP server tools (obyte_analyze_address,
obyte_analyze_unit, obyte_analyze_aa, obyte_resolve_asset, obyte_get_portfolio_summary,
obyte_prepare_aa_dry_run) without being asked. Pass network:"testnet" for testnet questions.
Never show raw smallest-unit amounts: use display_total fields or resolve decimals first.

Configuration

Precedence, highest first:

1. Per-network environment variable (e.g. OBYTE_TESTNET_HUB_ADDRESS)
2. Per-network CLI flag (e.g. --testnet-hub)
3. Plain environment variable / CLI flag (applies to the default network only)
4. Built-in default

Default hubs:

• Mainnet: https://obyte.org/api
• Testnet: https://testnet.obyte.org/api

Custom hub URL policy (applies to any hub override):

• https: is allowed.
• http: is allowed only for localhost, 127.0.0.1, and ::1.
• URL credentials are rejected.
• Non-HTTP protocols are rejected.

Updating

How users learn about updates

The server checks the npm registry once per process (3s timeout, fail-silent, disable with OBYTE_NO_UPDATE_CHECK=1) and surfaces the result in three places:

• obyte_get_network_info returns an update block (current, latest, update_available) — agents are instructed to mention available updates to the user.
• obyte-mcp doctor prints an update check line (informational, never fails doctor).
• On startup an update_available diagnostic is written to stderr (visible in client MCP logs).

Users who keep the default unpinned npx -y obyte-mcp config get new versions automatically on the next client restart — the notification mostly matters for pinned versions, .mcpb bundles, and global installs. Watch the GitHub repo (Releases) for changelogs.

How to update

The server runs through npx, which resolves the latest published version. How to move to a newer release depends on how it is registered:

• npx-based configs (default in every snippet above). npx caches packages. Clear the cache so the next launch fetches the newest version, then restart the client:

  Terminal

  Copy

  npx -y obyte-mcp@latest --version     # fetch + print the newest version
  npm cache clean --force               # optional: force-drop the npx cache
  

  You can also pin a version in your config, e.g. ["-y", "obyte-mcp@0.1.2"], and bump it when you want to update.

• Claude Desktop / Claude Code / VS Code / Codex. Nothing to re-register — they call the same npx command. Just refresh the package as above and restart the client. To re-run the installer (for example after changing flags), use --name to overwrite the same entry:

  Terminal

  Copy

  npx -y obyte-mcp@latest install
  

• .mcpb bundle. Rebuild the bundle from the new source (npm ci --omit=dev && npm run bundle) and re-install the new obyte-mcp.mcpb in Claude; it replaces the previous version.

• Global install (if you used npm i -g obyte-mcp). npm update -g obyte-mcp.

Check what you are running with npx -y obyte-mcp --version and npx -y obyte-mcp doctor.

Recommended Tools

Use these first for agent-facing tasks. All accept an optional network.

• obyte_analyze_address: balances with decimals-aware balance_summary, profile units, definition, attestations, optional history.
• obyte_analyze_unit: joint plus optional AA response chain.
• obyte_analyze_aa: AA balances with balance_summary, selected state vars, optional responses.
• obyte_resolve_asset: resolves asset/symbol/decimals in one call, returns explorer_asset_url (holders page).
• obyte_get_asset_holders: top holders of an asset (explorer-sourced), raw + display amounts, supply, up to 100 per call.
• obyte_prepare_aa_dry_run: validates and dry-runs an AA trigger.
• obyte_get_portfolio_summary: balances for up to 20 addresses with totals_by_asset display totals.

Raw Hub Tools

Advanced tools that mirror Obyte hub/client methods (each accepts an optional network):

• obyte_get_network_info (returns config for both networks)
• obyte_get_last_mci
• obyte_get_peers
• obyte_get_witnesses
• obyte_get_joint
• obyte_get_balances
• obyte_get_profile_units
• obyte_get_definition
• obyte_get_data_feed
• obyte_get_history
• obyte_get_attestation
• obyte_get_attestations
• obyte_get_aa_response_chain
• obyte_get_aa_responses
• obyte_get_aas_by_base_aas
• obyte_dry_run_aa
• obyte_execute_getter
• obyte_get_aa_balances
• obyte_get_aa_state_vars

Symbol Tools

• obyte_get_official_token_registry_address
• obyte_get_symbol_by_asset
• obyte_get_asset_by_symbol
• obyte_get_decimals_by_symbol_or_asset

Registry symbols are uppercase, so symbol inputs are uppercased before lookup: ousd and OUSD resolve to the same asset. Asset ids are base64 and stay case-sensitive. A symbol that is not in the selected registry comes back as asset: null, symbol: null with a note - never as a made-up match.

Base asset decimals (aliases are case-insensitive):

• base and GBYTE: 9
• MBYTE: 6
• KBYTE: 3
• BYTE: 0

Mainnet default token registry:

O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ

On testnet, configure a registry if you need symbol lookups (or pass token_registry_address per call):

npx -y obyte-mcp --testnet-token-registry YOUR_TESTNET_REGISTRY_AA

Tool Behavior

All tool responses are JSON text envelopes. meta.network and meta.hub report the network that answered the call.

Success:

{
  "ok": true,
  "meta": {
    "network": "testnet",
    "hub": "https://testnet.obyte.org/api",
    "tool": "obyte_get_balances",
    "request_id": "...",
    "duration_ms": 123,
    "retry_count": 0,
    "truncated": false
  },
  "data": {}
}

Error:

{
  "ok": false,
  "meta": {
    "network": "mainnet",
    "hub": "https://obyte.org/api",
    "tool": "obyte_get_balances",
    "request_id": "...",
    "duration_ms": 123,
    "retry_count": 0,
    "truncated": false
  },
  "error": {
    "code": "HUB_ERROR",
    "message": "...",
    "details": {}
  }
}

Error codes:

• VALIDATION_ERROR
• CONFIG_ERROR
• HUB_ERROR
• TIMEOUT
• NETWORK_ERROR
• OUTPUT_TOO_LARGE
• SECRET_INPUT_REJECTED
• INTERNAL_ERROR

Input Limits

• Address arrays: max 20
• Oracle arrays: max 10
• State var prefix: max 128 characters
• Generic JSON payloads: max 64KB
• All object schemas are strict and reject unknown fields (except the optional network)

Output Limits And Truncation

The server measures serialized UTF-8 output bytes. If output exceeds OBYTE_MAX_OUTPUT_BYTES, it truncates only data, never meta or error.

Strategy:

• Arrays keep the first items that fit and append { "__truncated__": true, "omitted_items": N }.
• Objects keep keys until the limit and add __truncated_keys__: { "omitted_keys": N, "first_omitted_keys": [...] } (the omitted list is summarized, never spelled out in full).
• Strings are cut at a UTF-8 safe boundary and end with ...[truncated].
• Map-like outputs such as AA state vars and balance maps are sorted by key before returning.
• If safe truncation cannot fit the envelope, the server returns OUTPUT_TOO_LARGE.

Truncation metadata:

• meta.truncated
• meta.output_bytes_before_truncation
• meta.output_bytes_after_truncation
• meta.truncation_reason

Retry Policy

The server retries only pure read tools.

Default:

• Max attempts: 2
• Backoff with jitter: about 250ms, then 750ms
• Retryable: transient network errors, timeout, HTTP 408, 429, 5xx
• Not retryable: validation errors, hub logical errors, most 4xx, secret guard failures
• Dry-run tools are not retried by default

Witnesses Cache

Witnesses are cached:

• In memory only
• Per process
• Per network + hub (so mainnet and testnet caches are independent)
• TTL: 10 minutes

obyte_get_witnesses accepts update=true to force refresh. obyte_get_history uses cached witnesses unless explicit witnesses are passed or update_witnesses=true.

Tool Annotations

All tools include MCP annotations:

• title
• readOnlyHint: true
• destructiveHint: false
• openWorldHint: true

Pure reads also include:

• idempotentHint: true

Dry-run tools are not marked idempotent.

Security Notes

Secret Guard

The server rejects the key material it never needs. Rejected field names:

• private_key / privkey
• secret_key
• seed / seed_phrase
• mnemonic
• xprv / tprv
• passphrase
• wif

Rejected values, regardless of field name: xprv/tprv extended keys and mnemonic-like phrases.

The guard is deliberately name-driven for hex. AA triggers and getter arguments legitimately carry opaque blobs - Ethereum txids (0x + 64 hex), sha256 hashes, and hash-timelock fields such as secret_hash - so a 64-character hex string is only rejected under a field name that claims to hold a key (key, sk, priv, wif), and never under a name about hashing. If a public value is still rejected, rename the field before calling the tool. This server never needs secrets.

Prompt Injection

Ledger data, AA state vars, token descriptions, symbols, profile data, and hub responses are untrusted external content. Agents must treat them as data, not instructions.

Symbol Registry Trust Model

Token registry mappings are convenience metadata, not proof that an asset is legitimate. Custom registries are explicitly user-trusted inputs. Symbols are not globally unique outside the selected registry.

Diagnostics

During MCP stdio runtime, stdout is reserved for JSON-RPC protocol messages only.

Diagnostics are written to stderr as JSON Lines:

{"ts":"2026-07-07T12:00:00.000Z","package":"obyte-mcp","level":"error","event":"mcp_stdio_error","message":"..."}

install, setup, doctor, --help, and --version do not start MCP stdio and can write normal output to stdout.

Resources

The server exposes:

• obyte://docs/overview
• obyte://docs/autonomous-agents
• obyte://docs/tools
• obyte://config/current
• obyte://examples/common-tasks
• obyte://security/trust-model

Prompts

The server exposes:

• analyze_obyte_address
• inspect_obyte_unit
• debug_aa_response
• resolve_obyte_asset
• plan_aa_dry_run
• summarize_portfolio

Common AI Tasks

Ask your MCP client:

• "Check this Obyte address balances on testnet and explain the assets."
• "Resolve this asset id to symbol and decimals on mainnet."
• "Who holds this asset?" (resolves it and links the explorer holders page)
• "Inspect why this AA trigger failed."
• "Dry-run this AA trigger on testnet."
• "Summarize AA state vars with this prefix."
• "Analyze this unit and follow the AA response chain."

MCP Inspector

Run against the published package:

npx -y @modelcontextprotocol/inspector npx -y obyte-mcp

Run against a local build:

npm install
npm run build
npx -y @modelcontextprotocol/inspector node dist/index.js

Distribution And Directory Listings

There is no single official CLI that installs an MCP server into every client at once. The official building blocks from https://github.com/modelcontextprotocol are:

• MCP Registry (server.json + mcp-publisher): discovery and distribution. Registry-aware clients and directories generate per-client install configs from it.
• MCP Bundles (.mcpb): one-click local install for Claude Desktop / Claude Code / MCP for Windows (see the bundle section above).

The obyte-mcp install command covers the remaining gap by driving each client's own CLI so one command reaches VS Code, Cursor, Codex, Claude Desktop, and Claude Code.

Official MCP Registry

The registry hosts metadata, not package artifacts. The npm package must already be published, and npm ownership is verified through the mcpName field in package.json:

{
  "mcpName": "io.github.Taump/obyte-mcp"
}

The matching registry metadata is in server.json. Publish a new npm version, then use mcp-publisher:

npm run typecheck
npm test
npm run build
npm publish

# macOS/Linux via release tarball
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
sudo mv mcp-publisher /usr/local/bin/

mcp-publisher login github
mcp-publisher publish

Verify publication:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Taump/obyte-mcp"

With GitHub authentication, the registry namespace must match the GitHub owner including its exact case: the registry builds the permission from the GitHub login verbatim and matches it case-sensitively (registry issue #689). The owner is Taump, so the name is io.github.Taump/obyte-mcp and mcpName in package.json must match it character for character - npm ownership validation compares the two exactly. Publish while authenticated as the account that owns Taump/obyte-mcp, or from a GitHub Action in that repository.

Local Development

git clone https://github.com/Taump/obyte-mcp.git
cd obyte-mcp
npm install
npm run typecheck
npm test
npm run build
node dist/index.js --help

Project structure:

• src/index.ts: CLI entrypoint (server / install / setup / doctor)
• src/cliArgs.ts: argument parsing
• src/config.ts: dual-network runtime config and URL policy
• src/server.ts: stdio MCP runtime (one hub client per network)
• src/obyteClient.ts: Obyte hub HTTP client
• src/tools.ts: MCP tool registration and per-call network routing
• src/install.ts: client CLI installer / Claude Desktop config writer
• src/configSnippets.ts: per-client config and command builders
• src/resources.ts, src/prompts.ts, src/symbols.ts, src/schemas.ts
• scripts/sync-version.mjs: propagates the package.json version to manifest.json / server.json

Compatibility Matrix

Release Checklist

package.json is the only place the version lives. src/constants.ts reads it at runtime, and scripts/sync-version.mjs propagates it to manifest.json and server.json (which cannot read it themselves). npm test fails if they ever drift, and npm publish re-syncs before packing.

npm version 0.3.0    # bump package.json, sync manifest.json + server.json, commit, tag
npm publish          # prepublishOnly: sync + typecheck + test + build

Editing package.json by hand works too - run npm run sync-version (or just publish, which does it for you). npm run sync-version -- --check reports drift without writing.

Publishing to npm only reaches users whose config is the unpinned npx -y obyte-mcp (all snippets above). The other channels have to be refreshed explicitly:

mcp-publisher publish    # MCP registry entry is version-pinned
npm run bundle           # rebuild obyte-mcp.mcpb, then attach it to the GitHub release

Before publishing:

npm run typecheck
npm test
npm run build
npm pack --dry-run
npx -y ./obyte-mcp-*.tgz --help

Also:

• Test the packed tarball with MCP Inspector.
• Test obyte-mcp install --dry-run for each client.
• Verify VS Code, Cursor, Codex, Claude Desktop, and Claude Code configs.
• Check that the Cursor and VS Code install badges still resolve.
• Build and install the .mcpb bundle in Claude Desktop.
• Publish an npm version containing mcpName.
• Publish server.json to the Official MCP Registry with mcp-publisher.
• Verify README examples match actual CLI output.
• Create a GitHub release with changelog and compatibility notes.