@aaronbassett/midnight-local-devnet

A CLI and MCP (Model Context Protocol) server for managing a local Docker-based Midnight development network. It spins up a Midnight node, indexer, and proof server in Docker containers, initializes a genesis master wallet pre-loaded with NIGHT tokens and DUST, and provides commands to fund test accounts, generate wallets, and monitor network health -- all from the command line or from any MCP-compatible AI assistant.

Prerequisites

• Node.js >= 22
• Docker (Docker Desktop or Docker Engine with Compose v2)

Quick Start

CLI

Start the network:

npx @aaronbassett/midnight-local-devnet start

Open the dashboard in your browser to monitor your devnet:

npx @aaronbassett/midnight-local-devnet dashboard

MCP Server

Add to your MCP client configuration (Claude Code, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "midnight-devnet": {
      "command": "npx",
      "args": ["-y", "-p", "@aaronbassett/midnight-local-devnet", "midnight-devnet-mcp"]
    }
  }
}

The MCP server communicates over stdio and exposes tools and resources that an AI assistant can use to manage the devnet on your behalf.

CLI Command Reference

All commands can be run via npx @aaronbassett/midnight-local-devnet <command>.

Global Options

| Option | Description | |---|---| | --json | Output results as machine-parseable JSON on stdout | | --version | Show version number | | --help | Show help |

When --json is active, only valid JSON is written to stdout. All progress messages and logs are redirected to stderr so the output can be piped directly to tools like jq.

Commands

| Command | Description | Options | |---|---|---| | start | Start the local Midnight devnet | --pull Pull latest Docker images | | stop | Stop the devnet | --remove-volumes Remove volumes and containers | | restart | Restart the network | --pull, --remove-volumes | | status | Show network status and per-service info | | | logs | Show network service logs | --service <name> (node, indexer, proof-server), --lines <n> (default: 50) | | health | Check health of all services | | | balances | Show master wallet NIGHT/DUST balances | | | fund <address> | Fund a Bech32 address with NIGHT tokens | --amount <n> Amount in NIGHT (default: 50,000) | | fund-file <path> | Fund all accounts from an accounts.json file | | | generate-accounts | Generate random test accounts | --count <n>, --format <mnemonic\|privateKey>, --output <path>, --fund, --register-dust | | dashboard | Open browser dashboard | --port <n> (default: 31780), --no-open Suppress auto-open | | interactive | Start interactive menu mode | |

Running with no arguments displays help.

JSON Output

Use the --json flag for scripting and automation:

# Get network status as JSON
npx @aaronbassett/midnight-local-devnet status --json

# Pipe to jq for filtering
npx @aaronbassett/midnight-local-devnet health --json | jq '.allHealthy'

# Generate accounts and capture output
npx @aaronbassett/midnight-local-devnet generate-accounts --count 3 --json > accounts.json

Errors in --json mode produce {"error": "message"} on stdout with a non-zero exit code.

Dashboard

The dashboard command starts a local server and opens a browser-based dashboard that displays the state of all local devnet services in real time.

npx @aaronbassett/midnight-local-devnet dashboard

This starts a server on http://localhost:31780 and opens your default browser. Press Ctrl+C in the terminal to stop.

Options:

• --port <n> -- Use a specific port (default: 31780, auto-increments if in use)
• --no-open -- Start the server without opening the browser

The dashboard shows:

• Node -- Block height, average block time, chain, peers, sync status, version
• Indexer -- Ready status, response time
• Proof Server -- Version, proof versions, job processing/pending/capacity gauge
• Wallet -- Master wallet NIGHT (unshielded + shielded) and DUST balances
• Response Times -- SVG sparkline charts of per-service response times
• Logs -- Combined color-coded log stream from all services, filterable by service, level, or text search

The dashboard connects to the server via WebSocket for live updates. If the connection drops, it auto-reconnects. You can start and stop the network directly from the dashboard using the action buttons.

The layout is responsive and adapts to your browser window width.

MCP Tool Reference

| Tool | Description | Parameters | |---|---|---| | start-network | Start the devnet (node, indexer, proof-server) | pull? boolean | | stop-network | Stop the devnet and close wallets | removeVolumes? boolean | | restart-network | Restart the network | pull? boolean, removeVolumes? boolean | | network-status | Get current network and per-service status | | | network-logs | Get recent logs from services | service? (node, indexer, proof-server), lines? number | | health-check | Check health of all service endpoints | | | get-network-config | Get endpoint URLs, network ID, image versions | | | get-wallet-balances | Get NIGHT and DUST balances of master wallet | | | fund-account | Transfer NIGHT to a Bech32 address | address string, amount? string | | fund-account-from-mnemonic | Derive wallet from mnemonic, fund NIGHT, register DUST | name string, mnemonic string | | fund-accounts-from-file | Batch fund accounts from accounts.json | filePath string | | generate-test-account | Generate random test accounts | format (mnemonic|privateKey), count?, fund?, registerDust?, outputFile? |

MCP Resource Reference

| URI | Description | |---|---| | devnet://config | Current network configuration: endpoints, network ID, Docker image versions | | devnet://status | Live network status including per-service container state |

Resources are read-only and can be accessed by any MCP client to display context to an AI assistant.

accounts.json Format

The fund-file CLI command and fund-accounts-from-file MCP tool accept a JSON file describing accounts to fund. Each account is identified by a mnemonic; the tool derives its wallet, transfers NIGHT tokens, and registers DUST.

{
  "accounts": [
    {
      "name": "Alice",
      "mnemonic": "abandon abandon abandon ... art"
    },
    {
      "name": "Bob",
      "mnemonic": "zoo zoo zoo ... vote"
    }
  ]
}

See accounts.example.json for a complete example with valid 24-word BIP39 mnemonics.

Each account entry requires:

• name -- A display label for the account.
• mnemonic -- A 24-word BIP39 mnemonic phrase.

Docker Services

The devnet runs three containers managed via Docker Compose:

| Service | Container Name | Image | Port | URL | |---|---|---|---|---| | Node | midnight-node | midnightntwrk/midnight-node:0.20.0 | 9944 | http://127.0.0.1:9944 | | Indexer | midnight-indexer | midnightntwrk/indexer-standalone:3.0.0 | 8088 | http://127.0.0.1:8088/api/v3/graphql | | Proof Server | midnight-proof-server | midnightntwrk/proof-server:7.0.0 | 6300 | http://127.0.0.1:6300 |

The indexer also exposes a WebSocket endpoint at ws://127.0.0.1:8088/api/v3/graphql/ws.

The network ID is undeployed (development mode).

Network Endpoints for DApp Development

When connecting a Midnight DApp to the local devnet, use the following configuration:

const config = {
  indexer: 'http://127.0.0.1:8088/api/v3/graphql',
  indexerWS: 'ws://127.0.0.1:8088/api/v3/graphql/ws',
  node: 'http://127.0.0.1:9944',
  proofServer: 'http://127.0.0.1:6300',
  networkId: 'undeployed',
};

You can also retrieve this configuration at runtime via the get-network-config MCP tool or the devnet://config MCP resource.

Development

To work on this project locally:

git clone https://github.com/devrelaicom/midnight-local-devnet.git
cd midnight-local-devnet
npm install
npm run build

Run the CLI from source:

node --enable-source-maps dist/cli.js start

Run the MCP server from source:

node --enable-source-maps dist/index.js

Run tests:

npm test

Troubleshooting

Docker containers fail to start

Make sure Docker is running and your user has permissions to use it:

docker info

If you see a permission error, add your user to the docker group or use sudo.

Port conflicts

The devnet uses ports 9944, 8088, and 6300. If another process is using one of these ports, stop it before starting the devnet:

lsof -i :9944
lsof -i :8088
lsof -i :6300

Containers are unhealthy

Run the health check to see which service is not responding:

npx @aaronbassett/midnight-local-devnet health

Check the logs for the failing service:

npx @aaronbassett/midnight-local-devnet logs --service node
npx @aaronbassett/midnight-local-devnet logs --service indexer
npx @aaronbassett/midnight-local-devnet logs --service proof-server

Clean restart

If the network is in a broken state, do a clean restart that removes all volumes:

npx @aaronbassett/midnight-local-devnet restart --remove-volumes

This removes all chain data and starts fresh.

Wallet sync takes too long

The master wallet must synchronize with the chain on first start. This can take 10--30 seconds depending on your machine. The CLI and MCP server wait for synchronization automatically.

"Network is not running" error

The tool detects running containers on startup. If you stopped the containers externally (e.g. via docker compose down), run start again:

npx @aaronbassett/midnight-local-devnet start

Acknowledgments

This project is based on midnight-local-network by @hbulgarini. Thank you for the initial version that made this possible.

License

MIT