Neo N3 MCP Server

MCP Server for Neo N3 Blockchain Integration | Version 1.6.0

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.6.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 r3enetwork/neo-n3-mcp:1.6.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 \
  r3enetwork/neo-n3-mcp:1.6.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 \
  r3enetwork/neo-n3-mcp:1.6.0

Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  neo-mcp:
    image: r3enetwork/neo-n3-mcp:1.6.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

🐳 Docker Quick Start

# Quick start with Docker Compose
git clone https://github.com/r3e-network/neo-n3-mcp.git
cd neo-n3-mcp
docker-compose -f docker/docker-compose.yml up -d

# Or build and run manually
npm run docker:build
npm run docker:run

# Development mode
npm run docker:up:dev

Production Docker Setup

# Build production image
./scripts/docker-build.sh --tag v1.6.0

# Run with custom configuration
docker run -d \
  --name neo-mcp-prod \
  -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -v neo-mcp-logs:/app/logs \
  neo-n3-mcp:v1.6.0

Development Docker Setup

# Build development image
./scripts/docker-build.sh --dev

# Run with hot reload and debugging
docker-compose -f docker/docker-compose.dev.yml up -d

🔧 Configuration Options

Environment Variables

Variable	Description	Default
NEO_NETWORK	Default network (mainnet/testnet)	testnet
NEO_MAINNET_RPC	Mainnet RPC endpoint	https://mainnet1.neo.coz.io:443
NEO_TESTNET_RPC	Testnet RPC endpoint	https://testnet1.neo.coz.io:443
LOG_LEVEL	Logging level (debug/info/warn/error)	info
LOG_FILE	Log file path	./logs/neo-mcp.log
WALLET_DIR	Wallet storage directory	./wallets

Command Line Options

Option	Description
--network	Set default network
--mainnet-rpc	Mainnet RPC URL
--testnet-rpc	Testnet RPC URL
--log-level	Set logging level
--log-file	Set log file path
--config	Load configuration from JSON file
--help	Show 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
• Rate Limiting: Configurable rate limiting for production deployments
• Secure Logging: No sensitive data exposed in logs

⚡ Performance & Reliability

• Rate Limiting: Built-in rate limiting with configurable thresholds
• Error Handling: Comprehensive error handling with proper MCP error codes
• Network Resilience: Automatic fallback mechanisms for RPC calls
• Production Ready: Systemd service configuration and monitoring support

🔄 Version Management & Release Process

Current Version: 1.6.0

This project follows Semantic Versioning with automated CI/CD pipeline for releases. See our Version Management Guide for detailed information.

🚀 How to Trigger Next Version Release

Method 1: Automated Release Script (Recommended)

# 1. First, do a dry run to see what will happen
./scripts/prepare-release.sh --type minor --dry-run

# 2. If everything looks good, run the actual release preparation
./scripts/prepare-release.sh --type minor

# 3. Push the changes (script will guide you)
git push

# 4. Create GitHub release (triggers full CI/CD pipeline)
gh release create v1.7.0 --generate-notes

Method 2: Manual NPM Version Commands

# Check current version
npm run version:check

# Bump version manually
npm run version:patch   # 1.6.0 → 1.6.1 (bug fixes)
npm run version:minor   # 1.6.0 → 1.7.0 (new features)
npm run version:major   # 1.6.0 → 2.0.0 (breaking changes)

# Then commit and push
git add . && git commit -m "chore: bump version to 1.7.0"
git push

Method 3: GitHub Release (Direct)

# Using GitHub CLI
gh release create v1.7.0 --generate-notes

# Or manually through GitHub web interface:
# 1. Go to https://github.com/r3e-network/neo-n3-mcp/releases
# 2. Click "Create a new release"
# 3. Tag: v1.7.0, Title: "Release v1.7.0"
# 4. Auto-generate release notes
# 5. Publish release

🔄 What Happens When You Create a Release

The automated CI/CD pipeline triggers the following workflow:

Phase 1: Testing & Validation ⚡

• ✅ Multi-version testing: Node.js 18.x, 20.x, 22.x on ubuntu-latest
• ✅ Code quality: Linting and type checking
• ✅ Unit tests: Core functionality validation
• ✅ Coverage reporting: Automatic upload to Codecov

Phase 2: Build & Docker 🔨

• ✅ TypeScript compilation: Build validation
• ✅ Docker builds: Both development and production images
• ✅ Container testing: Docker functionality validation
• ✅ Compose validation: Configuration testing

Phase 3: Security & Audit 🔒

• ✅ Security audit: npm audit for vulnerabilities
• ✅ Dependency check: audit-ci for security issues
• ✅ Package updates: Check for outdated dependencies

Phase 4: Publishing 📦 (Only on release)

• 🚀 NPM Publishing: Automatic package publishing to npm registry
• 🐳 Docker Publishing: Multi-tag image publishing to Docker Hub
• 📋 Versioned tags: Semantic versioning with proper tagging

Phase 5: Deployment 🌐 (Only on release)

• 🎯 Production deployment: Automated deployment notification
• 📊 Release tracking: Version monitoring and validation

📋 Release Types

Type	Version Change	Use Case	Example
patch	1.6.0 → 1.6.1	Bug fixes, security patches	./scripts/prepare-release.sh --type patch
minor	1.6.0 → 1.7.0	New features, enhancements	./scripts/prepare-release.sh --type minor
major	1.6.0 → 2.0.0	Breaking changes	./scripts/prepare-release.sh --type major

🎯 Quick Release Commands

# For next minor release (recommended for new features)
./scripts/prepare-release.sh --type minor

# For patch release (bug fixes)
./scripts/prepare-release.sh --type patch

# For major release (breaking changes)
./scripts/prepare-release.sh --type major

# Test what would happen (dry run)
./scripts/prepare-release.sh --type minor --dry-run

📊 Latest Changes (v1.6.0)

• ✨ Enterprise CI/CD Pipeline: Complete GitHub Actions workflow
• 🐳 Docker Infrastructure: Production and development environments
• 📁 Project Organization: Structured folders (docker/, docs/, scripts/)
• 🔧 Automated Publishing: NPM and Docker Hub integration
• 📚 Comprehensive Documentation: Guides for all deployment scenarios
• 🔄 Version Management: Automated release preparation and validation

📚 Release Documentation

• CHANGELOG.md - Complete version history
• VERSION_MANAGEMENT.md - Detailed release process
• WORKFLOW.md - CI/CD pipeline documentation

🔐 Required Secrets (Already Configured)

• ✅ NPM_TOKEN - For NPM registry publishing
• ✅ DOCKER_USERNAME - Docker Hub username
• ✅ DOCKER_PASSWORD - Docker Hub access token

📚 Documentation

• API Reference - Complete API documentation
• Architecture - System design and components
• Examples - Practical usage examples and best practices
• Docker Guide - Comprehensive Docker deployment guide
• Production Checklist - Production deployment guide
• Deployment - Deployment configuration
• Testing - Testing and validation
• Networks - Network configuration details
• Version Management - Release process and versioning
• Release Guide - Quick reference for triggering releases
• Workflow Guide - CI/CD pipeline documentation
• Changelog - Version history and changes

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• NPM Package: https://www.npmjs.com/package/@r3e/neo-n3-mcp
• Neo N3 Documentation: https://docs.neo.org/
• MCP Protocol: https://modelcontextprotocol.io/