Neo N3 MCP Server

MCP Server for Neo N3 Blockchain Integration | Version 2.0.0

A production-ready MCP server providing Neo N3 blockchain integration with 27 tools, 3 fixed resources, and a parameterized block resource for wallet management, transaction lifecycle tracking, asset transfers, contract deployment, 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. Environment Variables

The MCP stdio server reads configuration from environment variables.

NEO_NETWORK=both \
NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443 \
NEO_TESTNET_RPC=http://seed1t5.neo.org:20332 \
N3INDEX_API_BASE_URL=https://api.n3index.dev \
LOG_LEVEL=info \
LOG_FILE=./logs/neo-n3-mcp.log \
npx @r3e/neo-n3-mcp

Backward-compatible aliases are also accepted:

• NEO_MAINNET_RPC_URL
• NEO_TESTNET_RPC_URL
• NEO_NETWORK_MODE

When NEO_NETWORK=both, stdio tool calls without an explicit network default to mainnet. The HTTP entrypoint requires NEO_NETWORK=mainnet or NEO_NETWORK=testnet.

When a contract reference is a plain name and it is not in the local famous-contract registry, the server can fall back to https://api.n3index.dev for name-to-hash resolution before validating the contract on-chain.

2. MCP Client Configuration

Example Claude/Cursor configuration:

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": ["-y", "@r3e/neo-n3-mcp"],
      "disabled": false,
      "env": {
        "NEO_NETWORK": "testnet",
        "NEO_TESTNET_RPC": "http://seed1t5.neo.org:20332",
        "LOG_LEVEL": "info"
      }
    }
  }
}

3. Docker Configuration

Using Docker Hub Image

# Basic run
docker run -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -e LOG_CONSOLE=false \
  -e LOG_FILE=/app/logs/neo-n3-mcp.log \
  r3enetwork/neo-n3-mcp:2.0.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=http://seed1t5.neo.org:20332 \
  -e LOG_LEVEL=info \
  r3enetwork/neo-n3-mcp:2.0.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:2.0.0

Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  neo-mcp:
    image: r3enetwork/neo-n3-mcp:2.0.0
    ports:
      - "3000:3000"
    environment:
      - NEO_NETWORK=mainnet
      - NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443
      - NEO_TESTNET_RPC=http://seed1t5.neo.org:20332
      - LOG_LEVEL=info
      - LOG_FILE=/app/logs/neo-n3-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 v2.0.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:v2.0.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	Network mode: mainnet, testnet, or both	both
NEO_MAINNET_RPC	Mainnet RPC endpoint	https://mainnet1.neo.coz.io:443
NEO_TESTNET_RPC	Testnet RPC endpoint	http://seed1t5.neo.org:20332
N3INDEX_API_BASE_URL	Base URL for remote contract name lookup	https://api.n3index.dev
N3INDEX_ENABLED	Enable N3Index-backed name resolution	true
LOG_LEVEL	Logging level	info
LOG_FILE	Log file path	./logs/neo-n3-mcp.log
RATE_LIMITING_ENABLED	Enable HTTP rate limiting	true
MAX_REQUESTS_PER_MINUTE	Per-minute limit	60
MAX_REQUESTS_PER_HOUR	Per-hour limit	1000

Legacy aliases accepted:

• NEO_MAINNET_RPC_URL
• NEO_TESTNET_RPC_URL
• NEO_NETWORK_MODE

🛠️ MCP Client Integration

Claude Desktop / Cursor

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": ["-y", "@r3e/neo-n3-mcp"],
      "disabled": false,
      "env": {
        "NEO_NETWORK": "mainnet",
        "NEO_MAINNET_RPC": "https://mainnet1.neo.coz.io:443",
        "NEO_TESTNET_RPC": "http://seed1t5.neo.org:20332",
        "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: ['-y', '@r3e/neo-n3-mcp'],
  env: {
    NEO_NETWORK: 'mainnet',
    NEO_MAINNET_RPC: 'https://mainnet1.neo.coz.io:443',
    NEO_TESTNET_RPC: 'http://seed1t5.neo.org:20332',
  },
});

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

await client.connect(transport);

📊 Available Tools & Resources

🛠️ Tools (27 available)

• Network: get_network_mode, set_network_mode
• Blockchain: get_blockchain_info, get_block_count, get_block, get_transaction, get_application_log, wait_for_transaction
• Wallets: create_wallet, import_wallet, get_wallet
• Assets: get_balance, get_unclaimed_gas, get_nep17_transfers, get_nep11_balances, get_nep11_transfers, transfer_assets, estimate_transfer_fees
• Contracts: invoke_contract, deploy_contract, list_famous_contracts, get_contract_info, get_contract_status
• NeoFS: neofs_create_container, neofs_get_containers
• Advanced: claim_gas, estimate_invoke_fees

🌐 HTTP Endpoints

• Health & metrics: /health, /metrics
• Transactions: /api/transactions/:txid, /api/transactions/:txid/application-log, /api/transactions/:txid/wait
• Accounts: /api/accounts/:address/balance, /api/accounts/:address/unclaimed-gas, /api/accounts/:address/nep17-transfers, /api/accounts/:address/nep11-balances, /api/accounts/:address/nep11-transfers, POST /api/accounts/claim-gas
• Blocks: GET /api/blocks/:hashOrHeight
• Transfers: POST /api/transfers, POST /api/transfers/estimate-fees
• Contracts: GET /api/contracts/:reference, GET /api/contracts/:reference/status, POST /api/contracts/invoke, POST /api/contracts/invoke/estimate-fees, POST /api/contracts/:name/invoke, POST /api/contracts/deploy (requires confirm=true)
• Wallets: POST /api/wallets, POST /api/wallets/import, GET /api/wallets/:address

📁 Resources (3 fixed + 1 template)

• Status: neo://network/status, neo://mainnet/status, neo://testnet/status
• Parameterized Block: neo://block/{height}

🔐 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: 2.0.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 v2.1.0 --generate-notes

Method 2: Manual NPM Version Commands

# Check current version
npm run version:check

# Bump version manually
npm run version:patch   # 2.0.0 → 2.0.1 (bug fixes)
npm run version:minor   # 2.0.0 → 2.1.0 (new features)
npm run version:major   # 2.0.0 → 3.0.0 (breaking changes)

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

Method 3: GitHub Release (Direct)

# Using GitHub CLI
gh release create v2.1.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: v2.1.0, Title: "Release v2.1.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	2.0.0 → 2.0.1	Bug fixes, security patches	./scripts/prepare-release.sh --type patch
minor	2.0.0 → 2.1.0	New features, enhancements	./scripts/prepare-release.sh --type minor
major	2.0.0 → 3.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 (v2.0.0)

• ✅ npm Dependency: Replaced vendored neon-js 3.x with @cityofzion/neon-js@5.x from npm — no more bundled vendor code
• ✅ Full Type Safety: Zero any types in production code — proper neon-js types flow through the entire codebase
• ✅ Rate Limiting Enforced: Rate limiting is now integrated into HTTP and MCP request pipelines (was defined but never called)
• ✅ Config Validation: Server validates environment variables at startup and fails fast with descriptive errors
• ✅ Log Rotation: Logs rotate at 10MB with up to 3 rotated files retained
• ✅ Clean Package Surface: Only dist/, README.md, and LICENSE ship in the npm tarball

📚 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
• Migration Guide - Upgrading from v1.x to v2.0

Troubleshooting

Installation Issues

• neon-js fails to install: Ensure you have Node.js >= 18. Run npm cache clean --force and retry.
• TypeScript errors: This package ships with type definitions. Ensure your @types/node version matches your Node.js version.

Runtime Issues

• "Rate limit exceeded": The server enforces rate limits (default: 60 req/min). Configure with MAX_REQUESTS_PER_MINUTE or disable with RATE_LIMITING_ENABLED=false.
• "Invalid configuration": The server validates config at startup. Check the error message for which value is wrong.
• RPC connection errors: Verify your RPC URL is reachable. Default mainnet: https://mainnet1.neo.coz.io:443

📄 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/