Neo N3 MCP Server Documentation

The Neo N3 MCP Server is an implementation of the Model Context Protocol (MCP) that provides standardized access to Neo N3 blockchain features and famous smart contracts. This server allows AI systems to interact with the Neo N3 blockchain through a consistent interface, enabling a wide range of blockchain operations without requiring deep blockchain knowledge.

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol for AI systems to interact with external tools and resources. It provides a consistent interface for AI models to access capabilities outside of their training data, including blockchain operations, file systems, and more.

Key Features

  • Neo N3 Blockchain Access: Direct access to Neo N3 blockchain features, including block queries, transaction creation, and more.
  • Famous Contracts Support: Interact with well-known Neo N3 contracts like NeoFS, NeoBurger, Flamingo, and more.
  • Dual Network Support: Seamlessly switch between Neo N3 mainnet and testnet.
  • MCP Protocol Integration: Standardized interface for AI systems to interact with Neo N3 blockchain.
  • Advanced Wallet Management: Secure management of Neo N3 wallets and accounts.

Installation

You can install the Neo N3 MCP Server using npm:

npm install @r3e/neo-n3-mcp

Requirements

  • Node.js v14 or later
  • npm v6 or later

Global Installation

For global installation, which allows running the server from any directory:

npm install -g @r3e/neo-n3-mcp

Configuration

The Neo N3 MCP Server can be configured through environment variables or a configuration file.

Environment Variables

Variable Description Default
NEO_MAINNET_RPC_URL URL for Neo N3 mainnet https://mainnet1.neo.coz.io:443
NEO_TESTNET_RPC_URL URL for Neo N3 testnet https://testnet1.neo.coz.io:443
NEO_MCP_PORT Port number for the MCP server 8080
NEO_MCP_LOG_LEVEL Logging level (debug, info, warn, error) info

Configuration File

You can also provide a configuration file at ~/.neo-n3-mcp/config.json:

{
  "port": 3000,
  "network": "mainnet",
  "mainnetRpcUrl": "https://mainnet1.neo.coz.io:443",
  "testnetRpcUrl": "https://testnet1.neo.coz.io:443",
  "walletPath": "./wallets"
}

MCP Tools

The Neo N3 MCP Server provides a variety of tools for interacting with the Neo N3 blockchain.

Blockchain Tools

Tool Name Description
get_blockchain_info Get general Neo N3 blockchain information
get_block Get block details by height or hash
get_transaction Get transaction details by hash
get_balance Get asset balance for an address
transfer_assets Transfer assets between addresses
get_block_count Get the current block height of the Neo N3 blockchain

Contract Tools

Tool Name Description
list_famous_contracts List all supported famous Neo N3 contracts
get_contract_info Get details about a specific contract
invoke_contract_read Call a read-only contract method
invoke_contract_write Call a contract method that modifies state

Famous Contract Specific Tools

For each famous contract, specific tools are available:

NeoFS Tools
neofs_create_container Create a storage container in NeoFS
neofs_get_containers Get containers owned by an address
NeoBurger Tools
neoburger_deposit Deposit NEO to NeoBurger to receive bNEO tokens
neoburger_withdraw Withdraw NEO from NeoBurger by returning bNEO tokens
neoburger_get_balance Get bNEO balance of an account
neoburger_claim_gas Claim accumulated GAS rewards from NeoBurger
Flamingo Tools
flamingo_stake Stake FLM tokens on Flamingo
flamingo_unstake Unstake FLM tokens from Flamingo
flamingo_get_balance Get FLM token balance
NeoCompound Tools
neocompound_deposit Deposit assets into NeoCompound
neocompound_withdraw Withdraw assets from NeoCompound
neocompound_get_balance Get balance of deposited assets in NeoCompound
GrandShare Tools
grandshare_deposit Deposit assets into GrandShare pool
grandshare_withdraw Withdraw assets from GrandShare pool
grandshare_get_pool_details Get details about a GrandShare pool
GhostMarket Tools
ghostmarket_create_nft Create a new NFT on GhostMarket
ghostmarket_list_nft List an NFT for sale on GhostMarket
ghostmarket_buy_nft Buy a listed NFT on GhostMarket
ghostmarket_get_token_info Get information about an NFT on GhostMarket

Wallet Tools

Tool Name Description
create_wallet Create a new Neo N3 wallet
import_wallet Import a wallet from WIF, private key, or NEP-6 format
export_wallet Export a wallet to WIF or NEP-6 format
get_wallet_info Get detailed information about a wallet

API Reference

The Neo N3 MCP Server follows the MCP protocol for API endpoints. Here are the main endpoints:

Tool Management

Endpoint Method Description
/mcp/v1/tools/list POST List all available tools
/mcp/v1/tools/call POST Call a specific tool

Resource Management

Endpoint Method Description
/mcp/v1/resources/list POST List all available resources
/mcp/v1/resources/read POST Read a specific resource

Request and Response Format

All API endpoints use JSON for request and response bodies. Here's an example of calling a tool:

Request

{
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "name": "get_blockchain_info",
    "input": {
      "network": "mainnet"
    }
  },
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "blockHeight": 12345678,
    "blockTime": "2023-07-15T12:34:56Z",
    "network": "mainnet",
    "version": "3.0.0"
  },
  "id": 1
}

MCP Operation Reference

This section provides detailed documentation for each MCP operation supported by the Neo N3 MCP Server.

get_blockchain_info

Returns general information about the Neo N3 blockchain.

Parameters

Name Type Description Required
network string Network to use: "mainnet" or "testnet" No (default: "mainnet")

Returns

Returns an object with information about the blockchain:

{
  "blockHeight": 12345678,
  "blockTime": "2023-07-15T12:34:56Z",
  "network": "mainnet",
  "version": "3.0.0"
}

get_block_count

Returns the current block height of the Neo N3 blockchain.

Parameters

Name Type Description Required
network string Network to use: "mainnet" or "testnet" No (default: "mainnet")

Returns

Returns an object with information about the current block height:

{
  "count": 5123456,  // Current block height
  "network": "mainnet"  // Network that was queried
}

Example

// Using MCP client
const result = await client.callTool('get_block_count', {
  network: 'mainnet'
});
console.log(`Current block height: ${result.count}`);

Neo RPC Method

This operation calls the Neo N3 getblockcount RPC method. For more information, see the Neo documentation.

Contract Reference

The Neo N3 MCP Server supports various famous Neo N3 contracts. Here's a reference for each contract:

NeoFS

NeoFS is a decentralized storage system on the Neo N3 blockchain.

Contract Information

Name NeoFS
Mainnet Script Hash 0x50ac1c37690cc2cfc594472833cf57505d5f46de
Testnet Script Hash 0xccca29443855a1c455d72a3318cf605debb9e384

Operations

Operation Description Parameters
createContainer Create a storage container
  • ownerId (string): Owner ID of the container
  • rules (array): Container rules
deleteContainer Delete a storage container
  • containerId (string): Container ID to delete
getContainers Get containers owned by an address
  • ownerId (string): Owner ID to query containers for

NeoBurger

NeoBurger is a Neo N3 staking service.

Contract Information

Name NeoBurger
Mainnet Script Hash 0x48c40d4666f93408be1bef038b6722404d9a4c2a

Operations

Operation Description Parameters
depositNeo Deposit NEO to receive bNEO tokens
  • account (hash160): Account receiving bNEO
withdrawNeo Withdraw NEO by returning bNEO tokens
  • account (hash160): Account receiving NEO
  • amount (integer): Amount of bNEO to exchange
balanceOf Get bNEO balance of an account
  • account (hash160): Account to check balance for
claimGas Claim accumulated GAS rewards
  • account (hash160): Account claiming rewards

Troubleshooting

Common issues and their solutions:

Connection Issues

If you're experiencing connection issues to the Neo N3 blockchain:

  • Verify that the RPC URL is correct and accessible
  • Check your network connection
  • Try a different RPC provider
Wallet Access Issues

If you're having trouble accessing wallets:

  • Verify that the wallet file exists and is not corrupted
  • Check that the password is correct
  • Ensure the wallet format is supported (NEP-6, WIF)
Contract Interaction Issues

If contract interactions are failing:

  • Verify that the contract is available on the selected network
  • Check that the operation parameters are correct
  • Ensure you have sufficient GAS for the transaction

Common Error Codes

Error Code Description Solution
INVALID_PARAMS Invalid parameters provided Check the parameters according to the documentation
WALLET_ERROR Error accessing wallet Verify wallet path and password
RPC_ERROR Error communicating with Neo RPC Check RPC URL and network connection
CONTRACT_ERROR Error interacting with contract Verify contract availability and parameters

Getting Support

If you need additional help, you can: