Neo N3 MCP Server

@r3e/neo-mcpis an MCP server for Neo N3 blockchain queries and controlled, auditable transaction submission. It ships three entrypoints:

The two HTTP servers are unrelated and configured separately. SeeRemote MCP 2026 HTTPanddocs/remote-mcp-transport.md.

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

The package root exports the MCP server, HTTP server, services, network enums, and validated configuration:

import { NeoNetwork, NeoService } from '@r3e/neo-mcp'; const neo = new NeoService( 'https://testnet1.neo.coz.io:443', NeoNetwork.TESTNET, ); const blockCount = await neo.getBlockCount(); console.log({ blockCount, height: Math.max(0, blockCount - 1) });

NeoMcpServerexposesrun()andclose()for applications that manage the stdio transport lifecycle themselves.

The aliasesNEO_MAINNET_RPC_URL,NEO_TESTNET_RPC_URL, andNEO_NETWORK_MODEremain supported.

Remote RPC endpoints must use HTTPS. Plain HTTP is accepted for loopback RPC endpoints; settingNEO_ALLOW_INSECURE_RPC=trueexplicitly permits remote plaintext HTTP and should be limited to controlled development environments.

WhenNEO_NETWORK=both, read-only MCP calls without an explicit network use mainnet. Every state-changing call requires an explicit network and an idempotency key. The HTTP entrypoint rejectsboth; setNEO_NETWORK=mainnetorNEO_NETWORK=testnet.

Writes are disabled by default. To enable them, create an owner-only signer file outside the repository and configure durable state:

install -m 0600 /dev/stdin /run/secrets/neo-signer-wif export NEO_ENABLE_WRITES=true export NEO_SIGNER_WIF_FILE=/run/secrets/neo-signer-wif export NEO_WRITE_STATE_DIR=/var/lib/neo-mcp/write-operations export NEO_MCP_REQUEST_STATE_KEY="$(openssl rand -hex 32)" export HTTP_WRITE_APPROVAL_API_KEY="$(openssl rand -hex 32)"

The MCP and HTTP request schemas never accept WIFs, private keys, or passwords. MCP writes use the2026-07-28input_requiredflow. The server signs the opaquerequestState, binds it totools/call, expires it after ten minutes, and executes only after the re-entered response accepts the exact intent fingerprint. HTTP writes return a pending intent and require a separate approval request authenticated byHTTP_WRITE_APPROVAL_API_KEY.

Account intelligence remains evidence-first:analyze_account_graphexposes the replayable, network-scoped transfer graph and curated metadata only. The backend's deterministic exchange-sweep, coordinated-signer, community-affinity, and graph-similarity detector queue is deliberately not exposed as public identity data; pending candidates require human review before they can become curated metadata.

As of 2026-08-01, both production network detector timers have completed their detector rerun successfully. The resulting pending queue is operational review evidence only and is not returned byanalyze_account_graph.

This is a bespoke REST/JSON API, not an MCP transport. MCP clients cannot connect to it; they use the stdio entrypoint or theremote MCP transport.

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

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

{ "blockCount": 12346, "height": 12345 }

HTTP_CORS_ORIGINS=https://console.example.com,https://admin.example.com

curl -X POST http://127.0.0.1:3000/api/transfers \ -H "Authorization: Bearer $HTTP_API_KEY" \ -H "Idempotency-Key: transfer-2026-07-11-001" \ -H 'Content-Type: application/json' \ -d '{"network":"mainnet","toAddress":"Nb...","asset":"NEO","amount":"1"}'

curl -X POST http://127.0.0.1:3000/api/write-intents/INTENT_ID/approve \ -H "Authorization: Bearer $HTTP_WRITE_APPROVAL_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"fingerprint":"RETURNED_64_HEX_FINGERPRINT"}'

SeeAPI.mdfor the tool and route reference.

npm ci npm run build export MCP_HTTP_BEARER="$(openssl rand -hex 32)" NEO_NETWORK=mainnet npm run start:mcp-http

import { Client, StreamableHTTPClientTransport, } from '@modelcontextprotocol/client'; const transport = new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3001/mcp'), { authProvider: { token: async () => process.env.MCP_HTTP_BEARER }, }); const client = new Client( { name: 'my-client', version: '2.0.0' }, { capabilities: {}, versionNegotiation: { mode: { pin: '2026-07-28' } }, }, ); await client.connect(transport); const { tools } = await client.listTools();

See[remote-mcp-transport.mdfor the full configuration reference, an end-to-end local run against the Neo Explorer agent, production deployment guidance, and troubleshooting.

The production Compose file isdocker/docker-compose.yml. It defines two services from the same image:neo-mcpruns the REST API on port 3000, andneo-mcp-httpruns the remote MCP transport on port 3001. Each requires its own token, binds the host port to127.0.0.1by default, and persists wallet records in its own volume:

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

…