sui-mcp-server

sui-mcp-server

53-tool MCP server for the Sui blockchain. Gives AI agents direct access to wallets, DeFi, Move contracts, staking, analytics, and the full Sui RPC surface.

Built on the Model Context Protocol with the official @mysten/sui v2.11 SDK and @mysten/suins for name service.

Tested end-to-end on devnet and testnet — wallet creation, faucet, transfers, coin splitting/merging, transaction queries, Move inspection, staking, DeFi pool queries, and SuiNS resolution all verified.

Installation

Claude Code / Cursor / Windsurf

Add to your MCP config (~/.mcp.json):

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

Global Install

npm install -g sui-mcp-server
sui-mcp-server

From Source

git clone https://github.com/ExpertVagabond/sui-mcp-server.git
cd sui-mcp-server
npm install
npm run build
npm start

Tools (53)

Wallet Management (4)

Tool	Description
create_wallet	Create a new Ed25519 keypair. Keys are held in memory only — not persisted to disk.
import_wallet	Import from a Bech32-encoded private key (suiprivkey...).
list_wallets	List all wallets managed in the current session.
get_balance	Get SUI balance for any address.

Coin Operations (4)

Tool	Description
get_all_balances	Get all coin balances for an address (SUI + all other coin types).
get_coins	Get coin objects of a specific type owned by an address.
get_coin_metadata	Get metadata for a coin type (name, symbol, decimals, description).
get_total_supply	Get total circulating supply of a coin type.

Transfers (4)

Tool	Description
transfer_sui	Transfer SUI between addresses. Amount is in SUI (not MIST).
transfer_objects	Transfer one or more objects to a recipient.
merge_coins	Merge multiple coins into one. Handles gas coin conflicts automatically.
split_coins	Split a coin into multiple coins. Works even with single-coin wallets.

Object Queries (5)

Tool	Description
get_object	Get full details of any on-chain object by ID.
get_owned_objects	List objects owned by an address, with optional type filtering.
get_dynamic_fields	Get dynamic fields of an object (for tables, bags, etc.).
multi_get_objects	Batch-fetch up to 50 objects in one call.
get_object_history	Trace all transactions that touched a given object (provenance).

Transactions (4)

Tool	Description
get_transaction	Get full transaction details by digest — input, effects, events, object changes.
dry_run_transaction	Dry-run a transaction to preview effects without executing.
query_transactions	Search transactions by sender, recipient, input object, changed object, or Move function.
get_total_transactions	Get the total transaction count on the network.

Move Smart Contracts (7)

Tool	Description
move_call	Execute a Move function call. Supports object refs, integers, booleans, strings.
dev_inspect	Simulate a Move call without executing — returns results, gas cost, effects. No wallet needed.
get_normalized_module	Get a full Move module definition (functions, structs).
get_move_function	Get details of a specific Move function (params, return types, visibility).
get_move_struct	Get a Move struct definition (fields, abilities, type parameters).
get_package_modules	List all modules in a Move package with their functions and structs.
get_move_call_metrics	Get network-wide Move call metrics — most-called packages, modules, functions.

Staking (4)

Tool	Description
get_stakes	Get all staking positions for an address.
request_add_stake	Stake SUI with a validator.
request_withdraw_stake	Withdraw staked SUI.
get_validators	Get the full validator set with APY, commission rates, and stake amounts.

Events (1)

Tool	Description
query_events	Query on-chain events by type, sender, package, module, or transaction digest.

Network & Analytics (9)

Tool	Description
switch_network	Switch between mainnet, testnet, devnet, and localnet.
get_network_info	Get chain ID, epoch, gas price, and latest checkpoint.
get_latest_checkpoint	Get the latest checkpoint sequence number.
get_reference_gas_price	Get the current reference gas price in MIST.
get_checkpoint	Get detailed checkpoint data by sequence number.
get_epoch_info	Get historical epoch data (start/end times, stakes, gas summaries).
get_protocol_config	Get the Sui protocol configuration (limits, features, gas settings).
get_system_state	Get full system state: epoch, validators, stake distribution, storage fund.
get_committee_info	Get validator committee information for any epoch.

SuiNS Name Service (4)

Tool	Description
resolve_name	Resolve a SuiNS name (e.g. example.sui) to a Sui address.
resolve_address	Reverse-resolve an address to its SuiNS name(s).
suins_get_name_record	Get full name record — NFT ID, target address, expiration, metadata.
suins_get_price	Get SuiNS registration and renewal pricing by name length.

DeFi: Cetus DEX (2)

Tool	Description
cetus_get_pools	Query Cetus CLMM pools by coin types. Returns pool addresses, liquidity, fee rates.
cetus_get_pool	Get detailed pool data for a specific Cetus pool by object ID.

DeFi: DeepBook (1)

Tool	Description
deepbook_get_pool	Get DeepBook v3 order book data — pool state and dynamic fields.

DeFi: Token Tools (3)

Tool	Description
get_token_price	Get token price by querying DeFi pool reserves. Supports common token shortcuts.
swap_quote	Get a swap quote by simulating against a pool. Returns estimated output and gas cost.
list_common_tokens	List common Sui tokens with their full coin type addresses.

Faucet (1)

Tool	Description
request_faucet	Request SUI from the faucet (devnet and testnet only).

Token Shortcuts

Use symbol shortcuts instead of full coin type addresses in any tool:

Shortcut	Full Coin Type
SUI	0x2::sui::SUI
USDC	0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC
USDT	0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN
WETH	0xaf8cd5edc19c4512f4259f0bee101a40d41ebed738ade5874359610ef8eeced5::coin::COIN
DEEP	0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP

Networks

The server starts on devnet by default. Switch networks at any time with switch_network:

Network	RPC Endpoint
mainnet	https://fullnode.mainnet.sui.io:443
testnet	https://fullnode.testnet.sui.io:443
devnet	https://fullnode.devnet.sui.io:443
localnet	http://127.0.0.1:9000

Security

Warning: This server stores private keys in memory during runtime. For production use, take appropriate precautions.

Built-in protections:

• Keys are in-memory only — never written to disk, never logged, cleared on process exit.
• Private keys are redacted from all error messages (suiprivkey... → [REDACTED]).
• Addresses are truncated in error output to prevent leakage.
• Rate limiting: 120 calls per minute (sliding window).
• All inputs validated with Zod strict schemas — rejects unknown fields.

Production recommendations:

• Use a secure key management solution (hardware wallet, HSM, or vault) instead of in-memory keys for mainnet operations.
• Run the server in an isolated environment (container, sandbox, or restricted user).
• Implement network-level access controls — the stdio transport is local-only by default.
• Rotate keys regularly and use separate wallets for testing vs. production.
• Monitor wallet activity and set up alerts for unexpected transactions.
• Prefer dev_inspect and dry_run_transaction to preview effects before executing on mainnet.

Architecture

src/index.ts          # Single-file MCP server (~1,300 lines)
├── Tool definitions  # 53 tools with Zod input schemas
├── Tool handlers     # Switch-case dispatch with error handling
├── Wallet store      # In-memory Map<string, WalletEntry>
├── Rate limiter      # Sliding window (120/min)
└── Network switcher  # Multi-network SuiJsonRpcClient management

Dependencies:

• @modelcontextprotocol/sdk — MCP protocol (stdio transport)
• @mysten/sui v2.11 — Sui JSON-RPC client, transactions, keypairs, faucet
• @mysten/suins v1.0 — SuiNS name service queries
• zod — Input validation

Development

npm install           # Install dependencies
npm run build         # Compile TypeScript
npm run lint          # Type-check without emitting
npm test              # Run 59 integration tests (hits devnet + testnet + mainnet)
npm start             # Start the server (stdio)
npm run dev           # Watch mode

Verified Test Results

Tested on Sui devnet (epoch 42) and testnet (epoch 1049):

59 passed, 0 failed, 59 total

End-to-end verified:

• Wallet creation and import (Ed25519 + Bech32 private keys)
• Faucet airdrop (10 SUI on devnet)
• SUI transfers between wallets
• Coin split (single-coin gas handling) and merge
• Transaction details, gas costs, object changes
• Move call simulation via dev_inspect
• Validator queries (4 on devnet, 118 on testnet)
• SuiNS name records (mainnet)
• Cetus DEX pool queries (mainnet)
• Event and transaction search/filtering
• Protocol config, epoch history, checkpoint data

Roadmap

• GraphQL RPC migration (Sui JSON-RPC deprecated July 2026)
• Cetus/Aftermath/Scallop SDK integration (pending @mysten/sui v2 compatibility)
• NFT and Kiosk framework operations
• Event streaming via gRPC
• Move contract deployment and upgrade management

License

MIT — Matthew Karsten / Purple Squirrel Media