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/

Neo N3 MCP Server

Neo N3 MCP Server

🚀 Quick Start

Install from NPM

Basic Usage

⚙️ Configuration

1. Command Line Configuration

2. JSON Configuration

3. Docker Configuration

Using Docker Hub Image

Docker Compose

🐳 Docker Quick Start

Production Docker Setup

Development Docker Setup

🔧 Configuration Options

Environment Variables

Command Line Options

🛠️ MCP Client Integration

Claude Desktop

Custom MCP Client

📊 Available Tools & Resources

🛠️ Tools (34 available)

📁 Resources (9 available)

🔐 Security

⚡ Performance & Reliability

🔄 Version Management & Release Process

Current Version: 1.6.0

🚀 How to Trigger Next Version Release

Method 1: Automated Release Script (Recommended)

Method 2: Manual NPM Version Commands

Method 3: GitHub Release (Direct)

🔄 What Happens When You Create a Release

Phase 1: Testing & Validation ⚡

Phase 2: Build & Docker 🔨

Phase 3: Security & Audit 🔒

Phase 4: Publishing 📦 (Only on release)

Phase 5: Deployment 🌐 (Only on release)

📋 Release Types

🎯 Quick Release Commands

📊 Latest Changes (v1.6.0)

📚 Release Documentation

🔐 Required Secrets (Already Configured)

📚 Documentation

📄 License

🔗 Links

Related Servers

Kibana MCP Server

AI Image Generation

Liana-MCP

MCP Framework Starter

SonarQube

CAD-MCP

AI Develop Assistant

Repo Map

Shadcn UI MCP Server

Godot MCP