free and open source

AlkaFrost

Alkanes + SUBFROST

AlkaFrost is a free, open-source MCP server that makes any AI assistant fluent in building on Alkanes and SUBFROST.

  • runs on your machine
  • your own SUBFROST key
  • read-only
  • free and open source

AlkaFrost

svg
AlkaFrost mark
AlkaFrost mark

What it is

AlkaFrost is an open-source Model Context Protocol server that gives any MCP-capable assistant, such as Claude Code, Claude Desktop and Cursor, a knowledge and live chain-data layer for the Alkanes metaprotocol and the SUBFROST network.

Point your assistant at it and it can read the official docs, query the live chain, and scaffold contracts without leaving your editor. It runs entirely on your machine with your own SUBFROST API key: no accounts and no middleman.

20 tools

Across docs, chain data, dev scaffolds, and a local learning log.

A 119-doc corpus

Built from the official, public SUBFROST docs and alkanes-rs. Every corpus file carries its source link.

Read-only by design

It never signs, broadcasts, or touches your keys.

Running in three steps

QUICKSTART

1. Get a SUBFROST API key

AlkaFrost talks to the SUBFROST gateway with your own key. Get a SUBFROST API key — 50% off your first month

2. Clone and build

Requires Node.js 20 or newer.

git clone https://github.com/Aries-Labs-HQ/AlkaFrost-AI-MCP.git
cd AlkaFrost-AI-MCP
npm install
npm run build

3. Connect your assistant

For Claude Code, add it as a local stdio server:

Claude Code
claude mcp add --scope local --transport stdio alkafrost \
  -e SUBFROST_API_KEY=YOUR_KEY \
  -- node /absolute/path/to/AlkaFrost-AI-MCP/dist/index.js

Verify with claude mcp list, then /mcp in a session. Keep -e KEY=value right before --, which separates Claude's flags from the launch command.

Cursor, Claude Desktop and any other client that takes a JSON server config use this entry:

Cursor / Claude Desktop
{
  "mcpServers": {
    "alkafrost": {
      "command": "node",
      "args": ["/absolute/path/to/AlkaFrost-AI-MCP/dist/index.js"],
      "env": { "SUBFROST_API_KEY": "YOUR_KEY" }
    }
  }
}

Your key is sent only as the x-subfrost-api-key header to the SUBFROST gateway, never in a URL and never anywhere else. You can also put it in a local .env file, which the repo ignores.

Four layers

20 tools

Knowledge

A searchable corpus of the official SUBFROST docs (protocol, tokens, build guides, JSON-RPC, REST and CLI reference, platform limits), the alkanes-rs README and the Orbital reference contract.

alkafrost_search, alkafrost_doc, alkafrost_full_doc, alkafrost_catalog

Chain data

Live, read-only queries against the SUBFROST gateway with your key: holdings, contract metadata, bytecode, simulate, frBTC peg and DIESEL status, oracle reads, AMM pools, and a guarded RPC.

alkafrost_tokens_by_address, alkafrost_token, alkafrost_contract_meta, alkafrost_bytecode, alkafrost_simulate, alkafrost_frbtc_status, alkafrost_diesel_status, alkafrost_oracle_read, alkafrost_oracle_price, alkafrost_pools, alkafrost_pool_info, alkafrost_rpc

Dev

Protocol constants and contract scaffolds: wrap, unwrap, contract, orbital.

alkafrost_constants, alkafrost_scaffold

Learning

A local incident log. Your assistant records gotchas as it works and checks them before the next task. It is stored on your machine only.

alkafrost_incident_report, alkafrost_incident_query

Safety: read-only by design

AlkaFrost is analytics only. It never signs, broadcasts, or touches wallets or keys.

The alkafrost_rpc passthrough is allowlisted to read methods and explicitly blocks broadcast, spend and admin calls.

Scaffolds and constants are emitted for you to run in your own alkanes-cli, where you hold the keys.

The incident log writes only to your machine and sanitizes secrets, keys and paths out of every report.

Configuration

SUBFROST_API_KEY

Required for the chain-data tools. The docs and dev tools work without it.

SUBFROST_RPC / SUBFROST_REST

Optional gateway overrides. The default is the mainnet JSON-RPC; REST is derived from it.

ALKAFROST_INCIDENTS_PATH

Optional path for your local incident log. The default is data/incidents.jsonl, which the repo ignores.

Logs go to stderr only, because stdout is the MCP protocol channel. The doc index is built from the corpus at startup.

View the repo

MIT

AlkaFrost is open source under the MIT license. Fix a doc, add a read-only tool, or report a bug. View the repo