Neo N3 MCP
An MCP server for interacting with the Neo N3 blockchain.
Installation
npx neo-n3-mcpAsk AI about Neo N3 MCP
Powered by Claude Β· Grounded in docs
I know everything about Neo N3 MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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_URLNEO_TESTNET_RPC_URLNEO_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_URLNEO_TESTNET_RPC_URLNEO_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(requiresconfirm=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.xfrom npm β no more bundled vendor code - β
Full Type Safety: Zero
anytypes 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 --forceand retry. - TypeScript errors: This package ships with type definitions. Ensure your
@types/nodeversion matches your Node.js version.
Runtime Issues
- "Rate limit exceeded": The server enforces rate limits (default: 60 req/min). Configure with
MAX_REQUESTS_PER_MINUTEor disable withRATE_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/

