The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Midnight Cast listing page.
[!NOTE] This project extends the Midnight Network with additional developer tooling.
Read-only CLI and MCP server for the Midnight networks: network health, error decoding, transactions, contracts, DUST, and working code from Midnight's official examples. Think Foundry cast for Midnight, not a wallet or app scaffold.
Preview needs nothing else. Preprod and mainnet go through Blockfrost and need a free project ID for each; see Quick start.
Note: midnight-cast also installs a short alias,
mn, which runs the same commands. Other global CLIs (e.g.@mermaid-js/mermaid-cli,midnight-wallet-cli) install anmntoo, so these docs, the hints and the JSON output always saymidnight-cast.
Or step by step: midnight-cast ping preview && midnight-cast tip preview && midnight-cast versions preview
Requires Node.js 20+ (22+ recommended). Without Node.js, the release binaries install the same commands after checking the checksum:
On Windows, in PowerShell: irm https://github.com/Kanasjnr/midnight-cast/releases/latest/download/install.ps1 | iex. Where there's no curl, wget -qO- <same URL> | sh works too. Alpine needs libstdc++ and libgcc first (apk add libstdc++ libgcc). MIDNIGHT_CAST_VERSION=0.2.0 pins a release and MIDNIGHT_CAST_INSTALL_DIR picks the directory (default ~/.local/bin). Each archive carries build provenance: gh attestation verify <archive> --repo Kanasjnr/midnight-cast.
preflight)examples)| Area | Commands |
|---|---|
| Health | health, ping, tip, versions, preflight |
| Chain | block latest, block <height>, rpc |
| Errors | decode (ledger, pallet, 1010, jsonrpc, --raw) |
| Indexer | tx, contract, dust-status, dust-event, dust-events |
| Working code and background | examples, explain (dust, 1010, versions, transcript, sync) |
| Agents | mcp, agents init |
| Config | config init, config show |
No wallet keys. No signing or proving.
Example output:
Example output:
Example output:
Networks: preview, preprod, mainnet, local — use --network or MN_NETWORK.
Preprod and mainnet go through Blockfrost, since Midnight retired its hosted preprod and mainnet endpoints (mainnet on 30 September 2026, preprod on 9 October). Blockfrost project IDs are per network: create a free Midnight Preprod project, a Midnight Mainnet one, or both, on blockfrost.io, then:
Preview is still hosted by Midnight and needs no project ID. The project IDs are never printed. See docs/COMMANDS.md.
When something breaks, run these in order:
midnight-cast health — ping + sync + versions in one shot (preflight --address <wallet> before a first transaction)midnight-cast ping — services up?midnight-cast tip — indexer synced?midnight-cast versions — stack matches support matrix?midnight-cast decode — what does the error mean?midnight-cast tx — what happened on chain?An agent working on a Midnight project needs to know what the network is doing right now, what an error means, and what working code looks like. midnight-cast answers all three from live data and Midnight's own sources, in a form an agent can parse, and its MCP server can't change anything.
It sits next to two other sources an agent may already have. The Kapa answer engine answers questions from Midnight's documentation and examples. Midnight Expert gives agents skills and MCP tools for writing and verifying Compact and SDK code. midnight-cast is the part neither covers: the live state of preview, preprod and mainnet, the meaning of a specific error code on the ledger the network runs, whether a project's versions match the network, and which of Midnight's official examples shows a pattern.
Add --json to any command for one stable envelope: ok, data, a structured error with a kind and hint, any warnings, and next, the follow-up commands an expert would run. midnight-cast explain --json describes every command, option, exit code and error kind in one call, and schemas/ has a JSON Schema for each command's output. Exit codes are 0 for success, 1 for a failed check and 2 for a usage error. See JSON output.
Agents that speak MCP can use midnight-cast directly: midnight-cast mcp runs an MCP server on stdio with 14 tools, health, preflight, ping, tip, versions, block, tx, dust_event, dust_events, contract, dust_status, decode, explain and examples, each returning the same envelope. For example, in Claude Code:
A sandbox or CI image without Node.js can run the same server from the standalone binary: midnight-cast mcp.
rpc command, which passes any JSON-RPC method to a node, isn't an MCP tool.MIDNIGHT_CAST_NETWORKS limits which networks the model may query, for example preview,preprod.MIDNIGHT_CAST_MAX_CALLS_PER_MINUTE), so a looping agent can't exhaust public endpoints or a Blockfrost plan.decode, explain and examples work offline from data bundled with the release.To teach a coding agent when and how to use midnight-cast, add the guidance to your project: midnight-cast agents init --write appends a marked section to AGENTS.md (read by Codex, Cursor, Copilot, Gemini CLI, Windsurf, Aider and others; use --file CLAUDE.md for Claude Code), or install the portable skill with npx skills add Kanasjnr/midnight-cast --skill midnight-cast. The snippets are in docs/agents.
In Claude Code, one plugin installs the skill, the MCP server and a /midnight-cast:diagnose <network> [tx or error] command. When the plugin is enabled, Claude Code asks for optional Blockfrost project IDs for preprod and mainnet and keeps them in secure storage; left empty, an exported BLOCKFROST_PREPROD_PROJECT_ID or BLOCKFROST_MAINNET_PROJECT_ID is used. If you added the server with claude mcp add before, remove it with claude mcp remove midnight-cast so only the plugin's server runs:
docs/MCP.md has the setup for Codex, Gemini CLI, Cursor, VS Code and others, the network allow-list, and how the Blockfrost project ID stays out of the model's sight.
| Need | Where |
|---|---|
| Midnight errors, network issues, dev questions | Midnight Discord |
| midnight-cast bug or something not working | GitHub Issues |
| New command or feature idea | GitHub Issues (feature request) |
midnight-cast decode --raw "…" auto-detects 1010 envelopes, Custom(N), ledger error names, pallet module errors, and JSON-RPC codes from one pasted error. Use --network so the ledger map matches preview vs preprod. Pallet Transaction hints point to inner Custom(N), and codes 179–181 show grouped transcript context. For missing codes or protocol questions, use Discord and the Midnight docs.
Apache-2.0