sui-mcp

sui-mcp

Read-only MCP server for Sui blockchain analytics. 46 tools covering wallets, DeFi positions, NFTs, token prices, transaction decoding, fund tracing, pool discovery, staking, Move package analysis (disassembly + heuristic risk scan, no external binary), optional Move bytecode decompilation, and Move Registry (MVR) name resolution.

• No API keys, no wallet, no private keys — connects to public Sui endpoints (mainnet by default)
• 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
• 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

Transaction building tools return unsigned bytes for external signing — the server never handles keys.

Setup

Requires Node.js >= 20 (22+ recommended).

npm install
npm run build

Move Decompiler (optional)

Reading and analyzing Move code works out of the box with no extra setup: disassemble_module returns Move bytecode assembly via the GraphQL endpoint, and analyze_package summarizes a package's API and runs a heuristic risk scan. The decompiler below is only needed if you want higher-level, source-like output.

The decompile_module tool requires the Revela move-decompiler binary. Requires a Rust toolchain (rustup.rs).

npm run build:decompiler

This clones verichains/revela_sui, builds the decompiler, and copies the binary to bin/move-decompiler.

<details> <summary>Manual setup</summary>

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

Then set SUI_DECOMPILER_PATH to the binary path. </details>

Installation

Add to your MCP client config (Claude Code, Claude Desktop, Cursor, etc.):

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

Replace /absolute/path/to/sui-mcp with the actual path to this repository. The env block is only needed for the decompilation tool — omit it if you don't need decompile_module.

See .env.example for optional environment variables (network selection, custom RPC endpoints).

Tools (44)

Recommended Starting Points

| Tool | Description | |---|---| | identify_address | Identify what a Sui address is: wallet, package, validator, or object | | get_wallet_overview | Comprehensive wallet overview: balances, SuiNS name, staking, kiosks, recent txs | | get_transaction_history | Decoded activity feed with protocol names and human-readable actions | | analyze_token | Full token analysis: metadata, price, 24h change, supply, top holders |

Chain & Network

| Tool | Description | |---|---| | get_chain_info | Current chain ID, epoch, checkpoint height, timestamp, gas price | | get_checkpoint | Checkpoint details by sequence number or digest |

Objects

| Tool | Description | |---|---| | get_object | Object by ID with type, owner, JSON content, and display metadata | | list_owned_objects | List objects owned by an address with optional type filter | | list_dynamic_fields | Dynamic fields of an object (tables, kiosk contents, etc.) |

Coins & Tokens

| Tool | Description | |---|---| | get_balance | Balance of a coin type for an address (defaults to SUI) | | get_coin_info | Token metadata: name, symbol, decimals, description, supply | | search_token | Search tokens by name/symbol, with Aftermath Finance fallback | | get_token_prices | Current USD prices for tokens via Aftermath + CoinGecko | | get_historical_prices | Historical prices at a point in time via Pyth oracle |

Transactions & Events

| Tool | Description | |---|---| | get_transaction | Transaction by digest with protocol-decoded actions | | query_transactions | Filter transactions by sender, address, object, or function | | query_events | Filter events by type, sender, module, or checkpoint range |

DeFi

| Tool | Description | |---|---| | get_defi_positions | DeFi positions across Suilend, Cetus, NAVI, Scallop, Bluefin, Bucket | | find_pools | Discover liquidity pools by token pair (Cetus, DeepBook, Turbos) | | get_pool_stats | Pool reserves, fees, and prices for a given pool object ID |

NFTs

| Tool | Description | |---|---| | list_nfts | List NFTs owned by a wallet, including kiosk-stored NFTs | | list_nft_collections | Lightweight collection summary with counts | | get_top_holders | Top holders of an NFT collection or token |

Staking

| Tool | Description | |---|---| | get_validators | List validators with stake, commission, voting power | | get_validator_detail | Detailed validator info including credentials and stats | | get_staking_summary | Wallet's staking positions and pools |

Names

| Tool | Description | |---|---| | resolve_name | SuiNS name resolution (forward and reverse) |

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

| Tool | Description | |---|---| | mvr_resolve | Resolve one or many MVR names → package IDs. Accepts version-pinned names like @suins/core/3. | | mvr_reverse_resolve | Reverse-lookup: package addresses → MVR names. Useful for enriching raw addresses anywhere. | | mvr_get_package_info | Full record for a name: metadata, version, package_address, package_info ID, git source. | | mvr_search | Browse / search the registry. Supports substring search, pagination, and an is_linked filter for published packages. | | mvr_resolve_struct | Resolve @org/app::module::Type → canonical type tag at the type's defining-package address. |

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)

| Tool | Description | |---|---| | get_package | Move package modules, structs (with ordered fields), and functions | | get_move_function | Specific Move function signature and parameters | | get_package_dependency_graph | Package dependency analysis with recursive traversal | | analyze_package | Summarize a package's API + heuristic risk scan (no binary; accepts 0x id or MVR name) | | disassemble_module | Disassemble Move bytecode via GraphQL (no binary; accepts 0x id or MVR name) | | decompile_module | Decompile Move bytecode to source (requires decompiler binary) |

Transaction Building

| Tool | Description | |---|---| | build_transfer_sui | Build unsigned SUI transfer transaction | | build_transfer_coin | Build unsigned coin transfer with auto coin selection | | build_stake_sui | Build unsigned staking transaction | | build_unstake_sui | Build unsigned unstake transaction | | simulate_transaction | Dry-run a transaction to preview effects and gas cost |

Advanced

| Tool | Description | |---|---| | decode_ptb | Decode a Programmable Transaction Block from BCS bytes | | trace_funds | Multi-hop fund flow tracing (forward or backward) | | check_activity | Monitor address or object for new activity since a checkpoint |

License

MIT