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, work out who can actually sign for a multisig treasury, and tell a coordinated cluster from a crowd, then reconstruct it all on a timeline.

68 tools. It also covers the ordinary things: wallet overviews, DeFi positions, NFTs, prices and Move package analysis.

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, in 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, classified "distributor", so shared funding alone
    proves nothing here; the second-level timing clusters carry the case

Several wallets tracing back to one funder looks decisive until you measure the funder itself. A distributor with 1,623 recipients funds unrelated wallets all day, so shared funding on its own says very little. Every funding result includes the fan-out measurement for this reason.

Fan-out reports shape as well as size. Measured on the same day, a known exchange and a sybil funder had almost identical counterparty counts, 399 and 431, but very different flow. The exchange ran balanced at 0.73 out/in, deposits in and withdrawals out. The funder ran 9.78, paying many addresses and being paid by few.

Multisig

A Sui address is the hash of whatever authenticates it. For a multisig, the threshold, every member key and every weight are part of that hash, so the committee can be read off the address and checked by deriving it and confirming it reproduces the address.

Identify a wallet and its committee. identify_address returns the shape, every member address, and each member resolved to its own name, labels and SuiNS history.

identify_address(0x045dadba…)
  → authentication: multisig, 4-of-7, verified: true
    committee_members: 7, each with name/label/kind

See which keys are actually used. The committee is fixed by the address, but who signs varies per transaction. analyze_multisig reads that across the wallet's history.

analyze_multisig(0x045dadba…, max_transactions: 200)
  → transactions_examined: 8
    signer_sets: [0,1,3,4] x4, [1,2,3,4] x2, [0,2,3,4] x2
    always_present: [3, 4]
    dormant_members: [5, 6]
    active_signers_meet_threshold: true

dormant_members are keys that hold weight and have never used it. always_present are keys the wallet currently cannot move without. Both are reported against transactions_examined, since the claim is only as good as the window.

See who authorised one transaction. get_transaction returns an authorization block naming the keys that signed and the members that did not, plus the gas sponsor when there is one.

get_transaction(oxrJ3Bppuk…)
  → authorization[0]: sender, multisig 4-of-7
      signed_by:     [0, 1, 3, 4]
      did_not_sign:  [2, 5, 6]

Search backwards from keys to a treasury. Given addresses a trace has already linked, find_shared_multisig derives every committee they could form and returns the ones that exist on chain. This finds multisigs that never appeared in the trace, since a wallet is only visible if it transacted with something you looked at.

find_shared_multisig([0xafe2fafa…, 0xc848c5cc…])
  → candidates_checked: 4, found: 1
    0xcf4e7b88… 1-of-2, evidence_tier: chain-derived

See who else can spend it. A wallet can authorize up to eight other addresses to act for it through 0x2::address_alias. identify_address returns that set, so a fixed committee does not have to be read as the only way to move the funds.

identify_address(0x434d9c12…)
  → aliases: [0x66b816ed…, 0x33a86fba…]
    delegated_to: [0x66b816ed…, 0x33a86fba…]
    owner_can_authorize: false

aliases is the set as the chain holds it and delegated_to is that set without the wallet itself. Enabling the feature seeds the set with the wallet's own address, so an empty delegated_to means nobody else was authorized.

The set replaces the signer rather than extending it, so owner_can_authorize decides who controls the wallet. When it is false the wallet's own key can no longer sign for it and only delegated_to can move the funds. Measured across all 63 mainnet sets, 50 are in that state.

An alias is control read from chain state, so you may write that the address can authorize for the wallet. It is not evidence of shared ownership, since a custodian holds authority for a client. A key acting for many wallets is a service, and two mainnet keys already act for 22 each. The set is mutable, so it is true as of the read, and most wallets have never enabled the feature.

Clustering. build_wallet_edges emits a co_signer edge for any key that can spend a wallet on its own, and marks clusters built only from those chain-derived rather than heuristic. Keys sitting on more committees than the limit are treated as custody or wallet-provider keys and listed under excluded_co_signers instead of linking everyone who uses that provider.

Limits, also stated in the tool output. Member order is part of the address, so find_shared_multisig is factorial in committee size and refuses past five keys; it covers equal-weight committees only, so a nil result is not a negative finding. A wallet that has never sent a transaction cannot be classified at all, because it has produced no signature. It comes back as unknown rather than as an ordinary wallet.

zkLogin and passkey wallets go through the same path. zkLogin reports its OAuth issuer, which is all the chain discloses about the account.

What a result tells you about itself

Several tools qualify their own answers rather than returning a number that looks more certain than it is.

Is this coin the one you meant? A symbol is not an identifier on Sui. 8,008 mainnet coins share one with another, and imitators are named to be mistaken. analyze_token reports verified, and every balance change in a trace carries coin_verified:

-850 MAGMA (unverified, assumed scale)     coin_verified=false
+202.361728 USDC                           coin_verified=true

These are two separate marks. unverified refers to which coin it is. assumed scale refers to whether the amount is right: decimals for an unknown coin are a guess, and 47 of 289 imitators declare a different scale from the coin they imitate.

analyze_token narrows the guess by reading 0x2::coin_registry, Sui's canonical on-chain coin metadata, and decimals_source names where the scale came from:

analyze_token(0xdba34672…::usdc::USDC)
  → decimals: 6, decimals_source: coin_metadata
    verified: true
    coin_registry: { registered: true, regulated: regulated, regulated_cap_id: 0x699b3162… }

Being in that registry is not a vouch. Anyone who can publish a coin can register it, so an impostor's entry looks the same as the real asset's, and verified still reports only what the curated list says. The registry supplies chain-derived decimals, and whether an issuer holds a cap that can freeze holders.

decimals_source is one of coin_metadata, coin_registry, curated, symbol_scan or assumed. The last two carry a note saying what the scale rests on.

An ambiguous symbol returns candidates rather than a coin. USDC matches seven legitimate verified coins on Sui (Circle's, Wormhole's, Celer's), so picking one would misreport which asset moved.

Why did it fail? get_transaction returns the abort code with the package, module and function that raised it, and a clever error's constant name where the author defined one.

Who deployed this, and can they still change it? analyze_package and identify_address report publisher, the address that created the package, attributed to the lineage root. The UpgradeCap carries holder_status: burned means upgrade rights were renounced, which reduces risk, and is what 27 of every 30 departing caps did.

Has an issuer frozen this address? check_coin_restrictions reads the on-chain deny list in both directions. A frozen address usually holds none of the coin that froze it, so it checks every configured coin type rather than the ones it holds.

What moved that was not a coin? trace_funds reports object_flow, and get_transaction reports object_changes and object_transfers for one transaction. Sui is object-based, so a balance change only covers Coin<T>. An NFT, a Kiosk or a capability changes hands without producing one:

--- Hop 1 (2025-01-10 10:25:31 UTC) ---
Sender: 0x8c4f…5ee8
Action: Transfer to recipient
Objects:
  package::UpgradeCap ⚠  0x8c4f…5ee8 -> 0xeda2…6c2b
    Whoever holds this can publish new code for the package.