MCP 服务器

Animica

Read-only chain data, AI inference, verifiable quantum randomness, and mining stats for the Animica post-quantum L1 — 15 tools, no private keys.

README

Animica MCP Server

Registry & packaging mirror. The server source lives in the monorepo: https://github.com/animicaorg/all/tree/main/python/animica/mcp — it ships inside the animica PyPI wheel (animica.mcp.server, [mcp] extra). This repo holds the registry/packaging metadata (server.json, Smithery/Docker files) and contains zero server code, so it can never drift from the shipped implementation.

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.

The installable package is animica-mcp — a thin console wrapper around animica[mcp]; installing it pulls in the server 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 (serves MCP at /mcp).
sse — MCP_TRANSPORT=sse animica-mcp (legacy SSE clients).

The Dockerfile + smithery.yaml in this repo package the streamable-HTTP mode for Smithery and other container hosts (listens on $PORT, serves MCP at /mcp).

Security posture

Read + compute only. Chain access goes through a hard-coded allow-list of read-only JSON-RPC methods (RPC_READ_ALLOWLIST in the source); 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.