Metadata-Version: 2.5
Name: animica-mcp
Version: 0.2.0
Summary: Animica MCP server — chain, AI inference, quantum beacon and mining tools for MCP clients (wraps animica[mcp])
Project-URL: Homepage, https://animica.dev
Project-URL: Repository, https://github.com/animicaorg/animica-mcp
Project-URL: Documentation, https://animica.org/developers
Author-email: Animica <ai@3vdc.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,animica,blockchain,inference,mcp,mining,model-context-protocol,quantum
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: animica[mcp]>=10.1.0
Description-Content-Type: text/markdown

# animica-mcp

MCP (Model Context Protocol) server for the [Animica](https://animica.dev) 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`](https://pypi.org/project/animica/) package (`animica.mcp.server`); installing `animica-mcp` pulls it in and exposes the `animica-mcp` command.

## Install

```bash
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

```bash
claude mcp add animica -- uvx animica-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

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

### Cursor

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

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

### VS Code

Add to `.vscode/mcp.json`:

```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://github.com/animicaorg/all
- Core package: https://pypi.org/project/animica/
- Contact: ai@3vdc.com

## License

Apache-2.0

<!-- mcp-name: org.animica/animica -->
<!-- mcp-name: io.github.animicaorg/animica -->
