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: