Neo N3 MCP Server

An MCP server that provides seamless integration with the Neo N3 blockchain, allowing Claude to interact with blockchain data, manage wallets, transfer assets, and invoke smart contracts.

📚 Documentation

Website - Comprehensive website with documentation, user guides and examples
API Reference - Detailed API documentation for all tools and resources
Deployment Guide - Comprehensive deployment options and configuration
Testing Guide - Testing approach and instructions for verifying functionality
Architecture - Detailed system architecture and design decisions
Network Architecture - Dual-network support and configuration details
Network Configuration - Configure which networks (mainnet, testnet, or both) are enabled

🚀 Features

Dual Network Support: Interact with both Neo N3 mainnet and testnet networks in a single server
Blockchain Information: Query blockchain height, validators, and network status
Block & Transaction Data: Get detailed information about blocks and transactions
Account Management: Check balances, create and import wallets securely
Asset Operations: Transfer NEO, GAS, and other tokens between addresses
Smart Contract Interaction: Deploy and invoke smart contracts on the Neo N3 blockchain
Famous Contracts Support: Interact with NeoFS, NeoBurger, Flamingo, NeoCompound, GrandShare, and GhostMarket
Transaction Monitoring: Check detailed transaction status with confirmation tracking
Gas Fee Estimation: Calculate estimated gas fees for transfers before executing them
Resilient RPC Communication: Automatic retry mechanisms with exponential backoff
Security Focused: Input validation, secure wallet storage, and protection of private keys
Docker Support: Easy deployment with Docker and Docker Compose
One-Click Installation: Simple setup process for Claude integration

🔄 What's New in v1.0.8

Enhanced RPC Reliability: Using secure HTTPS endpoints for both networks:
- Mainnet: https://mainnet1.neo.coz.io:443
- Testnet: https://testnet1.neo.coz.io:443
Comprehensive Website: New website with detailed documentation, user guides, and integration examples
Improved Development Tools: Added rebuild scripts and dark mode support
Better Documentation: Enhanced documentation organization and readability

Configuration with MCP

You can easily add the Neo N3 MCP server to your Claude MCP configuration in different ways:

Using NPM (Recommended for Quick Start)

Add this to your claude_desktop_config.json or MCP settings:

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": [
        "-y",
        "@r3e/neo-n3-mcp"
      ]
    }
  }
}

This will automatically download and run the Neo N3 MCP server without any local installation.

Using Docker

Add this to your claude_desktop_config.json or MCP settings:

{
  "mcpServers": {
    "neo-n3": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "r3e/neo-n3-mcp"
      ]
    }
  }
}

To build the Docker image locally:

docker build -t r3e/neo-n3-mcp .

Installation

Using Docker (recommended)

# Clone the repository
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# Start the server with Docker Compose
docker-compose up -d

Manual Installation

# Clone the repository
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Adding to MCP Settings

To add the Neo N3 MCP server to your MCP settings, you can use the provided script:

# Build the project first
npm run build

# Add to MCP settings
npm run add-to-mcp

This will automatically add the Neo N3 MCP server to your Claude MCP settings file, making it available for use with Claude.

Configuration

The server can be configured using environment variables:

NEO_RPC_URL: Default URL of the Neo N3 RPC node (default: https://mainnet1.neo.coz.io:443)
NEO_MAINNET_RPC_URL: URL of the Neo N3 mainnet RPC node (default: same as NEO_RPC_URL or https://mainnet1.neo.coz.io:443)
NEO_TESTNET_RPC_URL: URL of the Neo N3 testnet RPC node (default: https://testnet1.neo.coz.io:443)
NEO_NETWORK: Default network type: 'mainnet' or 'testnet' (default: mainnet)
NEO_NETWORK_MODE: Network mode: 'mainnet_only', 'testnet_only', or 'both' (default: both)
WALLET_PATH: Path to the wallet files (default: ./wallets)
LOG_LEVEL: Log level: 'debug', 'info', 'warn', 'error' (default: info)
LOG_CONSOLE: Whether to log to console (default: true)
LOG_FILE: Whether to log to file (default: false)
LOG_FILE_PATH: Path to log file (default: ./logs/neo-n3-mcp.log)
MAX_REQUESTS_PER_MINUTE: Maximum number of requests per minute (default: 60)
REQUIRE_CONFIRMATION: Whether to require confirmation for sensitive operations (default: true)

Usage

Network Configuration Tools

The server provides tools to get and set the network mode at runtime:

get_network_mode

Get the current network mode configuration.

{
  "name": "get_network_mode",
  "arguments": {}
}

set_network_mode

Set the active network mode.

{
  "name": "set_network_mode",
  "arguments": {
    "mode": "testnet_only"
  }
}

Blockchain Tools

All tools support an optional network parameter to specify which network to use ('mainnet' or 'testnet').

get_blockchain_info

Get general information about the Neo N3 blockchain.

{
  "name": "get_blockchain_info",
  "arguments": {
    "network": "testnet"
  }
}

get_block

Get block details by height or hash.

{
  "name": "get_block",
  "arguments": {
    "hashOrHeight": 12345,
    "network": "mainnet"
  }
}

get_transaction

Get transaction details by hash.

{
  "name": "get_transaction",
  "arguments": {
    "txid": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "network": "testnet"
  }
}

get_balance

Get account balance for a specific address.

{
  "name": "get_balance",
  "arguments": {
    "address": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ",
    "network": "mainnet"
  }
}

transfer_assets

Transfer assets between addresses.

{
  "name": "transfer_assets",
  "arguments": {
    "fromWIF": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "toAddress": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ",
    "asset": "NEO",
    "amount": "1",
    "confirm": true,
    "network": "testnet"
  }
}

invoke_contract

Invoke a smart contract method.

{
  "name": "invoke_contract",
  "arguments": {
    "fromWIF": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "scriptHash": "0x8c23f196d8a1bfd103a9dcb1f9ccf0c611377d3b",
    "operation": "transfer",
    "args": [
      {
        "type": "Hash160",
        "value": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ"
      },
      {
        "type": "Hash160",
        "value": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ"
      },
      {
        "type": "Integer",
        "value": "1"
      },
      {
        "type": "Any",
        "value": null
      }
    ],
    "confirm": true,
    "network": "testnet"
  }
}

create_wallet

Create a new wallet.

{
  "name": "create_wallet",
  "arguments": {
    "password": "your-secure-password",
    "network": "mainnet"
  }
}

import_wallet

Import an existing wallet from WIF or encrypted key.

{
  "name": "import_wallet",
  "arguments": {
    "key": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "password": "your-secure-password",
    "network": "testnet"
  }
}

Resources

Neo N3 Network Status

Default network (based on configuration):

neo://network/status

Specific networks:

neo://mainnet/status
neo://testnet/status

Neo N3 Block by Height

Default network:

neo://block/{height}

Specific networks:

neo://mainnet/block/{height}
neo://testnet/block/{height}

Neo N3 Address Balance

Default network:

neo://address/{address}/balance

Specific networks:

neo://mainnet/address/{address}/balance
neo://testnet/address/{address}/balance

Testing

The Neo N3 MCP server includes comprehensive tests to ensure its functionality. There are multiple ways to run tests:

Using Jest (TypeScript Tests)

Jest tests provide comprehensive testing with proper mocking:

# Install dependencies first
npm install

# Run all Jest tests
npm test

# Run specific test files
npx jest tests/utils/validation.test.ts
npx jest tests/contracts/contract-service.test.ts

The test suite includes tests for:

Core Services:
- Neo service (blockchain interactions)
- Contract service (smart contract interactions)
Utilities:
- Validation (input parameter validation)
- Error handling (standardized error responses)
- Cache (in-memory caching with TTL)
- Rate limiting (request throttling)
Website Components:
- Main page functionality
- Documentation page navigation
- API playground interactions
- Block explorer functionality
- Chat interface

Using Simple Test Runner (JavaScript)

Simplified JavaScript test runners are also available for quick testing:

# Run the simplified test
node tests/simple-test.js

# Run network test
node tests/network-test.js

# Run transaction status test
node tests/transaction-status-test.js

These tests cover core API functionality without requiring TypeScript compilation.

Development and Contributing

Publishing

To publish the package to NPM and/or Docker registries:

# Publish to NPM
npm run publish:npm

# Build and publish Docker image
npm run publish:docker

# Publish to both
npm run publish:all

Development Setup

For development, use:

# Build with TypeScript watching
npm run dev

Security Considerations

Private keys are never exposed in responses
Sensitive operations (transfers, contract invocations) require explicit confirmation
Input validation is performed for all parameters
Error messages are designed to be informative without exposing sensitive information

Technical Details

Service Architecture

The Neo N3 MCP server is structured around several key components:

MCP Interface: Implemented in src/index.ts - Handles MCP protocol communication
Neo Service: Implemented in src/services/neo-service.ts - Core Neo N3 blockchain interactions
Validation: Implemented in src/utils/validation.ts - Parameter validation
Error Handling: Implemented in src/utils/error-handler.ts - Standardized error responses

Error Handling

Errors are standardized through the handleError function which:

Converts Neo N3 specific errors to user-friendly messages
Masks sensitive information
Provides clear actionable information to users

Networking

The server automatically handles network retries and errors when connecting to the Neo N3 blockchain network. Connection parameters like timeouts and retry attempts can be configured through environment variables.

Project Structure

The project is organized as follows:

neo-n3-mcp/
├── src/
│   ├── services/
│   │   └── neo-service.ts       # Core Neo N3 blockchain interaction
│   ├── utils/
│   │   ├── validation.ts        # Input validation
│   │   └── error-handler.ts     # Error handling and responses
│   ├── config.ts                # Configuration settings
│   └── index.ts                 # MCP server and tool definitions
├── tests/
│   ├── neo-service.test.ts      # Jest tests for NeoService
│   └── simple-test.js           # Simple JavaScript test runner
├── scripts/
│   ├── add-to-mcp-settings.js   # Script to add to MCP settings
│   ├── publish-npm.js           # Script to publish to NPM
│   └── publish-docker.sh        # Script to build and publish Docker image
├── wallets/                     # Wallet storage directory
├── dist/                        # Compiled TypeScript output
├── docker-compose.yml           # Docker Compose configuration
├── Dockerfile                   # Docker container definition
├── package.json                 # Node.js package definition
└── tsconfig.json                # TypeScript configuration

Acknowledgments

This project would not be possible without the following:

@cityofzion/neon-js - The official JavaScript SDK for Neo N3 blockchain, providing the core functionality for interacting with the Neo N3 network. Special thanks to the City of Zion team for their ongoing development and maintenance of this essential library.
MCP Protocol - For providing the standardized protocol for AI systems to interact with external tools and resources.

License

This MCP server is licensed under the MIT License. See the LICENSE file for details.

Famous Neo N3 Contracts Support

The Neo N3 MCP Server now includes support for interacting with famous Neo N3 contracts like:

NeoFS: Decentralized storage system on Neo N3 blockchain
NeoBurger: Neo N3 staking service
Flamingo (FLM): Neo N3 DeFi platform
NeoCompound: Automatic yield farming protocol on Neo N3
GrandShare: Profit sharing protocol on Neo N3
GhostMarket: NFT marketplace on Neo N3

Contract Tools

Listing and Information

list_famous_contracts: List all supported famous Neo N3 contracts
get_contract_info: Get details about a specific famous contract

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_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

Examples

Getting a List of Famous Contracts

const result = await callTool('list_famous_contracts', {
  network: 'mainnet'
});

Getting Contract Information

const result = await callTool('get_contract_info', {
  contractName: 'flamingo',
  network: 'mainnet'
});

Depositing to NeoBurger

const result = await callTool('neoburger_deposit', {
  fromWIF: 'your-private-key-wif-format',
  confirm: true,
  network: 'mainnet'
});

Staking on Flamingo

const result = await callTool('flamingo_stake', {
  fromWIF: 'your-private-key-wif-format',
  amount: '100',
  confirm: true,
  network: 'mainnet'
});

Depositing to NeoCompound

const result = await callTool('neocompound_deposit', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'your-password',
  assetId: '0xd2a4cff31913016155e38e474a2c06d08be276cf',
  amount: '100',
  network: 'mainnet'
});

Creating an NFT on GhostMarket

const result = await callTool('ghostmarket_create_nft', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'your-password',
  tokenURI: 'https://example.com/nft/metadata.json',
  properties: [
    { key: "artist", value: "ExampleArtist" },
    { key: "edition", value: "1/1" }
  ],
  network: 'mainnet'
});

const result = await callTool('grandshare_get_pool_details', {
  poolId: 1,
  network: 'mainnet'
});

Integrations

Neo N3 MCP Server

📚 Documentation

🚀 Features

🔄 What's New in v1.0.8

Configuration with MCP

Using NPM (Recommended for Quick Start)

Using Docker

Installation

Using Docker (recommended)

Manual Installation

Adding to MCP Settings

Configuration

Usage

Network Configuration Tools

get_network_mode

set_network_mode

Blockchain Tools

get_blockchain_info

get_block

get_transaction

get_balance

transfer_assets

invoke_contract

create_wallet

import_wallet

Resources

Neo N3 Network Status

Neo N3 Block by Height

Neo N3 Address Balance

Testing

Using Jest (TypeScript Tests)

Using Simple Test Runner (JavaScript)

Development and Contributing

Publishing

Development Setup

Security Considerations

Technical Details

Service Architecture

Error Handling

Networking

Project Structure

Acknowledgments

License

Famous Neo N3 Contracts Support

Contract Tools

Listing and Information

NeoFS Tools

NeoBurger Tools

Flamingo Tools

NeoCompound Tools

GrandShare Tools

GhostMarket Tools

Examples

Getting a List of Famous Contracts

Getting Contract Information

Depositing to NeoBurger

Staking on Flamingo

Depositing to NeoCompound

Creating an NFT on GhostMarket

Getting GrandShare Pool Details

Related MCP Servers

Ledger MCP Server

BrianKnows MCP Server

GOAT MCP Server

MCP Installer

Appeared in Searches