icon for mcp server

Neo N3 Blockchain Integration

STDIO

Standardized interface for AI agents to interact with Neo N3 blockchain.

Neo N3 MCP Server

MCP Server for Neo N3 Blockchain Integration | Version 1.5.0

MCP SDK Neo N3 NPM

A production-ready MCP server providing Neo N3 blockchain integration with 34 tools and 9 resources for wallet management, asset transfers, contract interactions, and blockchain queries.

🚀 Quick Start

Install from NPM

# Install globally
npm install -g @r3e/neo-n3-mcp

# Or install locally
npm install @r3e/neo-n3-mcp

Basic Usage

# Run with default configuration
npx @r3e/neo-n3-mcp

# Or if installed globally
neo-n3-mcp

⚙️ Configuration

1. Command Line Configuration

# Specify network
neo-n3-mcp --network testnet

# Custom RPC endpoints
neo-n3-mcp --mainnet-rpc https://mainnet1.neo.coz.io:443 --testnet-rpc https://testnet1.neo.coz.io:443

# Enable logging
neo-n3-mcp --log-level info --log-file ./neo-mcp.log

# Complete example
neo-n3-mcp \
  --network mainnet \
  --mainnet-rpc https://mainnet1.neo.coz.io:443 \
  --testnet-rpc https://testnet1.neo.coz.io:443 \
  --log-level debug \
  --log-file ./logs/neo-mcp.log

2. JSON Configuration

Create a neo-mcp-config.json file:

{
  "network": "mainnet",
  "rpc": {
    "mainnet": "https://mainnet1.neo.coz.io:443",
    "testnet": "https://testnet1.neo.coz.io:443"
  },
  "logging": {
    "level": "info",
    "file": "./logs/neo-mcp.log",
    "console": true
  },
  "server": {
    "name": "neo-n3-mcp-server",
    "version": "1.5.0"
  },
  "wallets": {
    "directory": "./wallets"
  }
}

Run with config file:

neo-n3-mcp --config ./neo-mcp-config.json

3. Docker Configuration

Using Docker Hub Image

# Basic run
docker run -p 3000:3000 r3e/neo-n3-mcp:1.5.0

# With environment variables
docker run -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -e NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443 \
  -e NEO_TESTNET_RPC=https://testnet1.neo.coz.io:443 \
  -e LOG_LEVEL=info \
  r3e/neo-n3-mcp:1.5.0

# With volume for persistent data
docker run -p 3000:3000 \
  -v $(pwd)/wallets:/app/wallets \
  -v $(pwd)/logs:/app/logs \
  -e NEO_NETWORK=testnet \
  r3e/neo-n3-mcp:1.5.0

Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  neo-mcp:
    image: r3e/neo-n3-mcp:1.5.0
    ports:
      - "3000:3000"
    environment:
      - NEO_NETWORK=mainnet
      - NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443
      - NEO_TESTNET_RPC=https://testnet1.neo.coz.io:443
      - LOG_LEVEL=info
      - LOG_FILE=/app/logs/neo-mcp.log
    volumes:
      - ./wallets:/app/wallets
      - ./logs:/app/logs
      - ./config:/app/config
    restart: unless-stopped

Run with:

docker-compose up -d

Custom Dockerfile

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/
COPY config/ ./config/

# Create necessary directories
RUN mkdir -p wallets logs

EXPOSE 3000

CMD ["node", "dist/index.js"]

🔧 Configuration Options

Environment Variables

VariableDescriptionDefault
NEO_NETWORKDefault network (mainnet/testnet)testnet
NEO_MAINNET_RPCMainnet RPC endpointhttps://mainnet1.neo.coz.io:443
NEO_TESTNET_RPCTestnet RPC endpointhttps://testnet1.neo.coz.io:443
LOG_LEVELLogging level (debug/info/warn/error)info
LOG_FILELog file path./logs/neo-mcp.log
WALLET_DIRWallet storage directory./wallets

Command Line Options

OptionDescription
--networkSet default network
--mainnet-rpcMainnet RPC URL
--testnet-rpcTestnet RPC URL
--log-levelSet logging level
--log-fileSet log file path
--configLoad configuration from JSON file
--helpShow help information

🛠️ MCP Client Integration

Claude Desktop

Add to your Claude Desktop config (~/.cursor/mcp.json or similar):

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": [
        "-y",
        "@r3e/neo-n3-mcp",
        "--network",
        "testnet"
      ],
      "disabled": false,
      "env": {
        "NEO_NETWORK": "testnet",
        "LOG_LEVEL": "info"
      }
    }
  }
}

For mainnet configuration:

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": [
        "-y",
        "@r3e/neo-n3-mcp",
        "--network",
        "mainnet"
      ],
      "disabled": false,
      "env": {
        "NEO_NETWORK": "mainnet",
        "NEO_MAINNET_RPC": "https://mainnet1.neo.coz.io:443",
        "NEO_TESTNET_RPC": "https://testnet1.neo.coz.io:443",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Custom MCP Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@r3e/neo-n3-mcp', '--network', 'mainnet']
});

const client = new Client(
  { name: 'my-neo-client', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

📊 Available Tools & Resources

🛠️ Tools (34 available)

  • Network: get_network_mode, set_network_mode
  • Blockchain: get_blockchain_info, get_block_count, get_block, get_transaction
  • Wallets: create_wallet, import_wallet
  • Assets: get_balance, transfer_assets, estimate_transfer_fees
  • Contracts: invoke_contract, list_famous_contracts, get_contract_info
  • Advanced: claim_gas, estimate_invoke_fees

📁 Resources (9 available)

  • Network Status: neo://network/status, neo://mainnet/status, neo://testnet/status
  • Blockchain Data: neo://mainnet/blockchain, neo://testnet/blockchain
  • Contract Registry: neo://mainnet/contracts, neo://testnet/contracts
  • Asset Information: neo://mainnet/assets, neo://testnet/assets

🔐 Security

  • Input Validation: All inputs validated and sanitized
  • Confirmation Required: Sensitive operations require explicit confirmation
  • Private Key Security: Keys encrypted and stored securely
  • Network Isolation: Separate configurations for mainnet/testnet

📚 Documentation

📄 License

MIT License - see LICENSE file for details.

🔗 Links

Be the First to Experience MCP Now