obyte-mcp

# 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.

[![Add obyte-mcp to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=obyte&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9ieXRlLW1jcCJdfQ==)
[![Install obyte-mcp in VS Code](https://img.shields.io/badge/VS_Code-Install_obyte--mcp-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=obyte&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22obyte-mcp%22%5D%7D)

## Quick Start

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

```bash
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):

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

Install into every detected client:

```bash
npx -y obyte-mcp install
```

Target a single client, or set the default network:

```bash
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):

```bash
./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"`:

```json
{
  "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](https://cursor.com/install-mcp?name=obyte&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9ieXRlLW1jcCJdfQ==) does the same in one click. To do it by hand, edit
`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) and restart Cursor:

```json
{
  "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):

```toml
[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:

```json
{
  "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:

```bash
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](https://github.com/modelcontextprotocol/mcpb) 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:

```bash
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 usual