Getting started

Run the MCP stdio server in a client, or start the HTTP entrypoint with conservative network and authentication defaults.

Prerequisite: Node.js 22 or newer. Docker is optional.

MCP stdio

Step 1

Run the package

npx -y @r3e/neo-n3-mcp
Step 2

Add it to an MCP client

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": ["-y", "@r3e/neo-n3-mcp"],
      "env": {
        "NEO_NETWORK": "testnet",
        "NEO_TESTNET_RPC": "https://testnet1.neo.coz.io:443"
      }
    }
  }
}

Stdio mode supports mainnet, testnet, or both. With both, read-only calls without an explicit network use mainnet. State-changing tools always require an explicit network and confirm: true.

Step 3

Make a read-only call

{
  "name": "get_block_count",
  "arguments": { "network": "testnet" }
}

The response contains blockCount and the latest zero-based height.

Build from source

git clone https://github.com/r3e-network/neo-n3-mcp.git
cd neo-n3-mcp
npm ci
npm run build
npm run verify

verify runs type checking, deterministic unit tests, a clean build, and deterministic built-server MCP tests.

Authenticated HTTP

HTTP requires NEO_NETWORK=mainnet or testnet. It binds to 127.0.0.1:3000 by default.

export HTTP_API_KEY="$(openssl rand -hex 32)"
NEO_NETWORK=testnet npm run start:http

A non-loopback HTTP_HOST requires an API key. Any configured key must contain at least 32 bytes.

curl http://127.0.0.1:3000/live
curl http://127.0.0.1:3000/health

curl -H "Authorization: Bearer $HTTP_API_KEY" \
  http://127.0.0.1:3000/api/blockchain/height

When a key is configured, /live and /health are unauthenticated. POST and PUT bodies must be JSON objects, and write requests require confirm to be the JSON boolean true.

Docker Compose

Production

export HTTP_API_KEY="$(openssl rand -hex 32)"
docker compose -f docker/docker-compose.yml up -d

The production definition requires the API key, publishes on host loopback by default, and persists /app/wallets.

Development

docker compose -f docker/docker-compose.dev.yml up -d

The development definition includes a local-only default key. Override it outside an isolated local environment.

Useful configuration

Next

API reference
Tools, resources, and HTTP behavior Testing
Deterministic, live, and stress suites Deployment
Containers, security, and rollback