@mcp3/sui NPM | npm.io

Sui MCP (Model Context Protocol)

A TypeScript implementation of the Model Context Protocol for the Sui Network.

Features

MCP server for integration with AI assistants
Connect to Sui network nodes
Download ABI (Application Binary Interface) for Sui packages
Call view functions with type arguments support
Query events from the Sui blockchain
TypeScript support
Command-line interface

Prerequisites

Node.js (v16 or higher)
pnpm (v7 or higher)

Installation

Clone the repository:

git clone <repository-url>
cd sui-mcp

Install dependencies:

pnpm install

Create a .env file in the root directory with your configuration:

SUI_RPC_URL=https://fullnode.mainnet.sui.io:443

Usage

MCP Server

The primary use case for this project is running an MCP server for integration with AI assistants.

Start the MCP server:

npx sui-mcp serve

The server provides the following tools for AI assistants:

sui-view-function: Call a view function for a given address (with type arguments support)
sui-download-abi: Get the ABI for a given object ID
sui-query-events: Query events from Sui RPC
sui-get-balance: Get the balance of a specific coin type for a wallet address
sui-get-all-balances: Get all coin balances for a wallet address
sui-get-coins: Get detailed information about coins owned by a wallet address
sui-get-coin-metadata: Get metadata for a specific coin type

CLI Usage

The project also provides a command-line interface for interacting with the Sui network.

Global Options

-n, --nodeUrl <nodeUrl>: Specify Sui RPC URL (defaults to value from .env or mainnet)
-v, --verbose: Enable verbose output

Commands

View Function

Call a view function for a given address:

npx sui-mcp view <package_module> <fn_and_params>

The function name can include type arguments in the format function<T0,T1>(arg1,arg2).

Example:

# Call a simple function
npx sui-mcp view 0x2::coin "total_supply(0x2::sui::SUI)"

# Call a function with type arguments
npx sui-mcp view 0x2::coin "balance<0x2::sui::SUI>(0x123)"

Get ABI

Get the ABI for a given package ID:

npx sui-mcp get-abi <object_id>

Options:

-j, --json: Output in JSON format
-l, --long-address: Display full addresses instead of shortened versions
-p, --public-only: Only show public functions (default: true)
-r, --read-only: Only show read-only non-void functions

Example:

# Get ABI for a package
npx sui-mcp get-abi 0x2

# Get ABI in JSON format
npx sui-mcp get-abi 0x2 --json

Query Events

Query events from Sui RPC:

npx sui-mcp query-events <filter>

Options:

-c, --cursor <cursor>: Pagination cursor (JSON string)
-l, --limit <limit>: Maximum number of events to return (default: 50)
-d, --descending: Sort events in descending order
-j, --json: Output in JSON format

Filter formats: 1. txId - e.g., "0x123..." 2. package::module::type - e.g., "0x2::coin::CoinEvent"

Examples:

# Get events by transaction digest
npx sui-mcp query-events 0x123abc

# Get events with a specific type
npx sui-mcp query-events 0x2::coin::CoinEvent

# Get events from a specific module
npx sui-mcp query-events 0x2::coin

Development

To run the project in development mode:

npm run dev

Building

To build the project:

npm run build

API Documentation

MCP Server

The MCP server is the primary way to use this project. It provides a server that can be integrated with AI assistants.

import { startServer } from 'sui-mcp';

// Start the MCP server
await startServer({ nodeUrl: 'https://fullnode.mainnet.sui.io:443' });

Core Functions

Call View Function

import { callViewFunction } from 'sui-mcp';

// Call a view function
const result = await callViewFunction({
  nodeUrl: 'https://fullnode.mainnet.sui.io:443',
  packageId: '0x2',
  module: 'coin',
  functionName: 'balance',
  params: ['0x123'],
  typeArguments: ['0x2::sui::SUI']
});

Download ABI

import { downloadABI } from 'sui-mcp';

// Download ABI for a package
const abi = await downloadABI(nodeUrl, packageId);

Query Events

import { queryEvents, parseEventFilter } from 'sui-mcp';

// Query events
const filter = parseEventFilter('0x2::coin::CoinEvent');
const events = await queryEvents({
  nodeUrl: 'https://fullnode.mainnet.sui.io:443',
  filter,
  limit: 10,
  descending: false
});

Get Balance

import { SuiClient } from '@mysten/sui/client';

// Get balance for a specific coin type
const client = new SuiClient({ url: 'https://fullnode.mainnet.sui.io:443' });
const balance = await client.getBalance({
  owner: '0x123...',
  coinType: '0x2::sui::SUI' // Optional, defaults to SUI if not specified
});

// Get all balances for a wallet
const allBalances = await client.getAllBalances({
  owner: '0x123...'
});

// Get coins owned by a wallet
const coins = await client.getCoins({
  owner: '0x123...',
  coinType: '0x2::sui::SUI', // Optional
  limit: 50 // Optional
});

// Get metadata for a specific coin type
const metadata = await client.getCoinMetadata({
  coinType: '0x2::sui::SUI'
});