horizen-mcp

An MCP server that gives coding agents accurate, sourced facts about the Horizen chain — so they stop guessing.

When you ask an agent to deploy a contract on Horizen, configure a bridge, or integrate Stork oracle or zkVerify, it needs ground truth: the right chain ID, the right RPC URL, the right contract address. This server provides that — typed, versioned, with explicit provenance on every value. If something isn't in the registry, the agent is told so explicitly rather than making something up.

Requirements

• Node.js >= 20
• A Stork API key in the STORK_API_KEY environment variable, only if you use the live fetch_stork_price tool.

Quickstart

Published on npm as @horizen/horizen-mcp.

Claude Code

Add it to your project's .mcp.json:

{
  "mcpServers": {
    "horizen": {
      "command": "npx",
      "args": ["-y", "@horizen/horizen-mcp"]
    }
  }
}

Claude Desktop

Edit the Claude Desktop config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "horizen": {
      "command": "npx",
      "args": ["-y", "@horizen/horizen-mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "horizen": {
      "command": "npx",
      "args": ["-y", "@horizen/horizen-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "horizen": {
      "command": "npx",
      "args": ["-y", "@horizen/horizen-mcp"]
    }
  }
}

Cline (VS Code)

Open the Cline extension, go to the MCP Servers tab, choose Edit MCP Settings, and add:

{
  "mcpServers": {
    "horizen": {
      "command": "npx",
      "args": ["-y", "@horizen/horizen-mcp"]
    }
  }
}

Continue (VS Code / JetBrains)

Add to ~/.continue/config.yaml:

mcpServers:
  - name: horizen
    command: npx
    args: ["-y", "@horizen/horizen-mcp"]

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "horizen": {
      "command": "npx",
      "args": ["-y", "@horizen/horizen-mcp"],
      "env": {}
    }
  }
}

Restart your editor after saving. The server starts on demand — no separate process to manage.

Stork API key (for fetch_stork_price)

Only the fetch_stork_price tool needs a key. It makes a live authenticated call to the Stork REST API, so supply a Stork API key through the STORK_API_KEY environment variable in your server config, alongside command and args:

{
  "mcpServers": {
    "horizen": {
      "command": "npx",
      "args": ["-y", "@horizen/horizen-mcp"],
      "env": { "STORK_API_KEY": "your-stork-api-key" }
    }
  }
}

The key is read from the environment and is never passed as a tool argument, so it stays out of the model's context and your chat history. Every other tool works without it. If your config file is committed to git (for example a project .mcp.json), reference the variable rather than hardcoding the key, e.g. "STORK_API_KEY": "${STORK_API_KEY}", so the secret stays out of the repo.

What you can ask

Once connected, your agent has access to Horizen chain facts through natural language:

Network info

"What's the Horizen mainnet chain ID and RPC URL?" "Give me the testnet explorer URL for Horizen."

Contract addresses

"What's the Stork oracle address on Horizen?" "What's the PureFi verifier proxy address I should integrate against?" "Is Uniswap deployed on Horizen mainnet?"

Tokens

"What's the cbBTC address and decimals on Horizen?" "List the tokens on Horizen with their decimals."

Oracle feeds and prices

"What's the Stork feed ID for ETHUSD on Horizen?" "How do I derive a Stork feed ID for a custom asset?" "Fetch the live signed Stork price for ETHUSD." (needs STORK_API_KEY)

Bridges

"How do I bridge assets to Horizen?" "Does Stargate support ETH on Horizen?"

Integrations and proofs

"How do I integrate Stork oracle on Horizen?" "Can I use Den from the command line, or is it browser-only?" "Can I use zkVerify with Horizen? What's the contract address?" "Has zkVerify aggregation 42 on domain 1 been posted to Horizen?"

Tools

| Tool | What it does | |-------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | get_chain_info | Chain ID, RPC/WS URLs, explorer, gas token, settlement layer for mainnet or testnet | | get_contract_address | Verified address for a given contract + network. Returns explicit not-found on miss — never fabricates. | | list_contracts | All contracts in the registry with per-network deployment status | | get_token_info | Addresses and decimals for ZEN, cbBTC, USDC.e on Horizen, plus cross-chain addresses | | get_stork_feed_id | Stork oracle feed ID for an asset (e.g. ETHUSD), computed via keccak256 | | get_bridge_info | Bridge URLs, supported assets, and caveats — native bridge vs. Stargate | | get_integration_info | Docs paths, access method, status for Stork, Goldsky, PureFi, Den, zkVerify | | fetch_stork_price | Live authenticated pull from the Stork REST API for a signed price update. Network call; reads STORK_API_KEY from the environment. | | check_zkverify_status | Reads the zkVerify aggregation proxy on Horizen to confirm a proof aggregation. On-chain read. |

Most tools are offline lookups against the bundled registry. fetch_stork_price (Stork REST API) and check_zkverify_status (on-chain read) are the two that make live network calls.

Every response includes a source field and a verified date. If a value isn't in the registry, the agent gets an explicit not-found with a list of what is known — never a guess.

Run from source

git clone https://github.com/HorizenOfficial/horizen-mcp
cd horizen-mcp
npm install
npm run build
node dist/index.js

To point your editor at a local build instead of npm:

{
  "mcpServers": {
    "horizen": {
      "command": "node",
      "args": ["/path/to/horizen-mcp/dist/index.js"]
    }
  }
}

Development

npm run dev        # watch mode — recompiles on save
npm run inspect    # MCP Inspector UI for interactive tool testing
npm test           # smoke test: builds, boots the server, and lists its tools

The Inspector lets you call any tool directly and inspect the full JSON response before connecting to an editor.

Data

All facts live in data/chain-facts.json. Tool handlers query this file — nothing is hardcoded in source. To update a value, edit that file and run npm run build.

Every entry carries a source (URL or attribution) and a verified date. Values that haven't been confirmed are left as null rather than guessed — the tool will tell the agent the value is unknown rather than returning something fabricated.

Contributing

See CONTRIBUTING.md for how to add contracts, integrations, or tools.

License

MIT