animica-mcp

animica-mcp

MCP (Model Context Protocol) server for the Animica AI + blockchain network. One command gives any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, …) 15 read/compute tools: OpenAI-compatible AI inference, a verifiable quantum randomness beacon, read-only chain and account lookups, mining-pool stats, and Studio compute cost estimates.

This package is a thin console wrapper around animica[mcp] — the server implementation lives in the animica package (animica.mcp.server); installing animica-mcp pulls it in and exposes the animica-mcp command.

Install

pip install animica-mcp
# or run it without installing:
uvx animica-mcp

Tools (15)

Tool	What it does
animica_info	Orientation: what Animica is, the AI API, quantum beacon, endpoints, docs. Start here.
animica_ai_ask	Ask Animica's ENA AI a question (OpenAI-compatible chat inference).
animica_ai_models	List the AI models available on Animica's OpenAI-compatible API.
animica_ai_job_status	Read the status of an ENA AI request/job by id (read-only).
animica_quantum_beacon_latest	Latest round of the verifiable quantum randomness beacon.
animica_quantum_draw	Compute a verifiable quantum-random draw off a beacon round (lottery, choice, weighted, shuffle, range, coin, dice, bytes).
animica_quantum_verify	Re-verify a quantum-random draw client-side — pure offline compute.
animica_qdna_verify_gene	Verify a qDNA training-genome gene seal (tamper-evidence) — pure offline compute.
animica_chain_head	Chain head: current height/hash and chain id. Read-only.
animica_chain_block	Read a block by height or hash (head block with neither). Read-only.
animica_chain_account	Balance + nonce for an anim1… address. Read-only — no keys, no signing.
animica_pool_stats	Live mining-pool stats: pool status plus active miner count.
animica_network_hashrate	Current network hashrate from the chain.
animica_studio_estimate	Estimate the ANM cost of an Animica Studio run before paying — local quote, charges nothing.
animica_studio_functions	List functions deployed to Animica Studio. Read-only.

Client setup

Claude Code

claude mcp add animica -- uvx animica-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "animica": {
      "command": "uvx",
      "args": ["animica-mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "animica": {
      "command": "uvx",
      "args": ["animica-mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "animica": {
      "type": "stdio",
      "command": "uvx",
      "args": ["animica-mcp"]
    }
  }
}

If you installed with pip install animica-mcp, replace "command": "uvx", "args": ["animica-mcp"] with "command": "animica-mcp" in any of the configs above.

Configuration (environment variables)

All endpoints default to public Animica infrastructure — the server works with zero configuration.

Variable	Default	Purpose
ANIMICA_BASE_URL	https://pool.animica.org/v1	OpenAI-compatible inference API base (chat + models). https://animica.dev/v1 is the free keyless endpoint if you prefer it.
ANIMICA_RPC_URL	https://rpc.animica.org/rpc	Node JSON-RPC endpoint (read-only calls).
ANIMICA_POOL_URL	https://pool.animica.org	Mining-pool stats API.
ANIMICA_BEACON_URL	https://pool.animica.org	Quantum randomness beacon (/beacon/*).
ANIMICA_API_KEY	(empty)	Optional Bearer key for the inference API; not required.
ANIMICA_MODEL	anm-fast-8b	Default model for animica_ai_ask.
ANIMICA_MCP_TIMEOUT_S	60	HTTP timeout (seconds) for backend calls.
MCP_TRANSPORT	stdio	Transport: stdio (default), streamable-http, or sse.

Transports

• stdio (default) — what Claude Code / Claude Desktop / Cursor / VS Code use; just run animica-mcp.
• streamable-http — MCP_TRANSPORT=streamable-http animica-mcp serves HTTP on 127.0.0.1:8765. For host/port flags use the full CLI from the animica package: animica mcp serve --transport http --host 0.0.0.0 --port 8765.
• sse — MCP_TRANSPORT=sse animica-mcp (legacy SSE clients).

Security posture

• Read + compute only. Chain access goes through a hard-coded allow-list of read-only JSON-RPC methods; mutating methods (send, sign, deploy, claim) are not on the list and cannot be reached, even by a bug.
• No keys. The server never handles private keys, never signs, never spends, and never mutates wallet state.
• Quantum draw/verify and qDNA gene verification are pure local compute and work fully offline.

Links

• Homepage: https://animica.dev (free OpenAI-compatible AI API at https://animica.dev/v1)
• Developer docs: https://animica.org/developers
• Explorer: https://explorer.animica.org
• Mining pool: https://pool.animica.org
• Monorepo: https://gitlab.com/Animica/animica-core
• Core package: https://pypi.org/project/animica/
• Contact: [e-mail]

License

Apache-2.0