sui-mcp

Read-only MCP server for investigating activity on Sui. Trace where funds went, attribute wallets to their funding sources, rank addresses by protocol flow, and tell a coordinated cluster from a crowd — then reconstruct it all on a timeline.

59 tools. It also does the ordinary things well — wallet overviews, DeFi positions, NFTs, prices, Move package analysis — but the reason to pick this one is the forensics.

Install

Add this to your MCP client config — Claude Code, Claude Desktop, Cursor, or anything else that speaks MCP over stdio:

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

No account, API key, or config file is required. The server reads public Sui endpoints and defaults to mainnet. Requires Node.js >= 22.13.

Doing investigative work? Start with the forensics tools loaded:

"env": { "SUI_TOOLS": "core,forensics" }

What an investigation looks like

Ranking a lending protocol's wallets for a day, then testing whether a cluster is coordinated — six calls:

aggregate_events(module: <package>, from: "2026-08-07T00:00:00Z", to: "now")
  → every event type it emits, with counts and the numeric fields available
    (user actions are usually far rarer than bookkeeping events)

aggregate_events(event_type: <DepositEvent>, value_field: "event.deposit_value", value_scale: 100)
  → wallets ranked by USD deposited, truncated: false

find_funding_sources(addresses: [...25], depth: "first_hop")
  → 23 of 25 share one funder, funded in three bursts of under a minute

get_address_fanout(<that funder>)
  → 1,623 recipients — "distributor", so co-funding alone proves nothing;
    the second-level timing clustering is what carries it

That last step is the point. Several wallets tracing to one funder looks decisive until you measure the funder. Every funding result carries that measurement so a coincidence doesn't get reported as a link.

Fan-out reports shape as well as size, because size alone doesn't separate the cases that matter. Measured on the same day, a known exchange and a sybil funder had almost identical counterparty counts — 399 and 431 — and completely different flow: the exchange ran balanced at 0.73 out/in (deposits in, withdrawals out) while the funder ran 9.78 (it pays many and is paid by few). One is noise in an investigation; the other is the thing you're looking for.

Tool profiles

All 59 tools loaded at once cost about 14k tokens of context on every request, and a large flat tool list makes models pick the wrong tool. So the server starts with a core set of 17 and keeps the rest one call away.

When you ask for something outside the current set — "trace where these funds went" — the model calls enable_tools and the tracing tools appear immediately, no restart. You never have to pick a profile.

To start with more, set SUI_TOOLS:

"env": { "SUI_TOOLS": "core,forensics" }

Runtime switching relies on notifications/tools/list_changed. Claude Code and Claude Desktop honour it; some clients cache the tool list and will only see the change after a restart. SUI_TOOLS always works, so set it explicitly if your client doesn't refresh.

Upgrading from 1.1.x, where every tool loaded at startup? Set SUI_TOOLS=all to keep that behaviour.

No wallet, no keys

The server has no credentials and no ability to move funds:

• It never accepts a private key, mnemonic, or seed phrase. No tool takes one as an argument and nothing in the code reads one from the environment.
• It never submits a transaction. build_transfer and build_staking return unsigned BCS bytes that you sign and broadcast somewhere else; simulate_transaction dry-runs bytes against a fullnode without executing them.
• Every remaining tool is a read.
• No provider accounts. RPC, indexing, and price data all come from public endpoints.

What the process actually does

Supply-chain scanners report the capabilities a package uses, without the reason. Here is the full list for this one:

There is no eval, no dynamic require, no minified or obfuscated code, and no telemetry. Inputs that come from the chain are treated as untrusted: decompile_module validates module names before they reach a filesystem path, and bounds how many modules one call will process.

Most of the dependency tree is the MCP SDK. This server speaks stdio only and imports just server/mcp.js and server/stdio.js, so the SDK's HTTP-transport dependencies are installed but never loaded.

Verifying a release

Releases are published from CI with npm provenance, so every tarball carries a signed attestation tying it to the commit and workflow run that produced it:

npm audit signatures

Capabilities

• Per-call network — every tool takes an optional network arg (mainnet / testnet / devnet); query multiple networks in one session (e.g. compare a testnet value to mainnet). SUI_NETWORK sets only the default.
• Protocol-aware — decodes transactions from Cetus, Suilend, NAVI, Scallop, Bluefin, DeepBook, and more into human-readable actions
• Incident investigation — labeled fund tracing, batch funding attribution with fan-out controls, multi-address timelines, object provenance, PTB anomaly triage, oracle-vs-market deviation
• Move package analysis — disassembly, heuristic risk scan, capability audit, and upgrade diffing, none of which need an external binary
• Multi-source architecture — gRPC for low-latency reads, GraphQL for filtered queries, archive node fallback for historical data
• Price aggregation — Aftermath Finance, Pyth oracles, and CoinGecko in a single unified interface
• Kiosk-aware — resolves NFT ownership through Sui's kiosk system to actual wallet addresses
• Move Registry (MVR) — resolves names like @deepbook/core to package addresses, and back

Configuration

All environment variables are optional. See .env.example for the full list; the common ones are SUI_NETWORK (default network), SUI_FULLNODE_URL / SUI_GRAPHQL_URL (custom RPC endpoints), and SUI_LABELS_FILE (address attribution labels for fund tracing).

Optional local store

Set SUI_STORE_PATH to keep address labels and fan-out measurements across sessions. It uses Node's built-in node:sqlite, so it adds no dependency and no native build. Unset by default — nothing is written to disk unless you ask for it, which matters because an investigation store is a record of which addresses you looked at.

"env": { "SUI_STORE_PATH": "/Users/you/.local/share/sui-mcp/store.db" }

Fund traces are deliberately not cached: a trace is a function of your labels, so a stored one would silently disagree with a fresh run the moment a label changed.

{
  "mcpServers": {
    "sui": {
      "command": "npx",
      "args": ["-y", "sui-analytics-mcp"],
      "env": { "SUI_NETWORK": "testnet" }
    }
  }
}

Move decompiler (optional)

58 of the 59 tools need nothing beyond the install above. Only decompile_module requires an external binary, and there are lighter options before you reach for it:

• disassemble_module returns Move bytecode assembly via the GraphQL endpoint.
• analyze_package summarizes a package's API and runs a heuristic risk scan.
• diff_package_upgrade diffs two versions of a package.

Use the decompiler when you want higher-level, source-like Move output instead of bytecode.

The binary is Revela's move-decompiler, built from Rust. It is not bundled in the npm package because a published tarball could only carry one platform's build, so you compile it once yourself and point the server at it with SUI_DECOMPILER_PATH. This works the same whether you installed via npx or from source. You need a Rust toolchain (rustup.rs); the build takes a few minutes.

git clone --depth 1 https://github.com/verichains/revela_sui.git
cd revela_sui/external-crates/move
cargo build --release --bin move-decompiler
# binary lands at target/release/move-decompiler

Then add its absolute path to your client config:

{
  "mcpServers": {
    "sui": {
      "command": "npx",
      "args": ["-y", "sui-analytics-mcp"],
      "env": {
        "SUI_DECOMPILER_PATH": "/absolute/path/to/revela_sui/external-crates/move/target/release/move-decompiler"
      }
    }
  }
}

If you already cloned this repo, npm run build:decompiler does the same clone and build and copies the result to bin/move-decompiler.

Without SUI_DECOMPILER_PATH the server falls back to looking for move-decompiler on PATH. Prefer the absolute path: desktop clients often launch servers with a minimal environment that doesn't include your shell's PATH, so a binary you can run in a terminal may still be invisible to the server. If it's found in neither place, decompile_module returns an error explaining how to fix it, and the other 56 tools are unaffected.

Running from source

For development, or to run a version you've modified:

git clone https://github.com/0xfreak0/sui-mcp.git
cd sui-mcp
npm install
npm run build

Then point your client at the build output instead of npx:

{
  "mcpServers": {
    "sui": {
      "command": "node",
      "args": ["/absolute/path/to/sui-mcp/dist/index.js"]
    }
  }
}

See CONTRIBUTING.md for the development and release workflow.

Tools (59)

Recommended Starting Points

Chain & Network

Objects

Coins & Tokens

Transactions & Events

DeFi

DeepBook

DeepBook v3 is a central limit order book, so it has no reserves — depth, spread and traded price come from the DeepBook indexer rather than from a pool object. Mainnet and testnet only.

NFTs

Staking

Names

Move Registry (MVR)

The Move Registry maps human-readable package names like @suins/core or @deepbook/core to on-chain package addresses. Backed by mainnet.mvr.mystenlabs.com/v1 (or testnet.mvr... when SUI_NETWORK=testnet).

Typical flows:

• "What's the package for @deepbook/core?" → mvr_resolve(['@deepbook/core']) → 0x4874e1.... Hand the address to get_package for module/function details.
• "What is package 0xf22f…?" → mvr_reverse_resolve(['0xf22f…']) → @suins/core.
• "Find DeepBook-related packages" → mvr_search('deepbook', limit=20, is_linked=true) → paginated list.
• "Pin to a specific version" → mvr_resolve(['@suins/core/3']) returns the v3 package address rather than the latest.

Packages (Developer)

Transaction Building

Advanced

Incident Investigation

License

MIT