Content
# AvaxOps
**AI-native operations layer for Avalanche validators and L1s.**
🔗 **Live site:** [avax-ops.vercel.app](https://avax-ops.vercel.app)
Ask your AI agent: *"Which of my validators need attention this week?"* — and get a real answer.
## Components
- **`mcp-server/`** — Open-source MCP server exposing Avalanche ops tools (validator health, expirations, balances, diagnostics) to Claude, Cursor, Claude Code, or any MCP-compatible agent. MIT licensed.
- **`service/`** *(planned, M2)* — Monitoring backend: polls P-Chain and node health, evaluates alert thresholds (uptime → 90% ACP-267 limit, expiring validations, low L1 balances, version lag).
- **`bot/`** *(planned, M2)* — Telegram bot for node registration, real-time alerts, and weekly fleet digests.
## Status
**v0.1 — MCP server with 5 working tools, verified against live Fuji and mainnet P-Chain APIs.**
Built for the Avalanche Team1 Builder Grants program; see `docs/grant-application.md` for the roadmap.
## MCP tools
| Tool | What it does |
|------|--------------|
| `ping` | Server + P-Chain connectivity check (network, chain height). |
| `list_validators` | Fleet table: stake (AVAX), uptime, connectivity, delegators, start/end, days remaining. |
| `expiration_report` | Validators whose validation period ends within N days (default 30). |
| `validator_health` | Per-validator report incl. the **ACP-267 90% uptime check**; optionally reads your node's own Info/Health APIs (version, bootstrap status, health checks). |
| `balance_check` | P-Chain address balances (total/unlocked/locked) and L1 validator continuous-fee balances with runway estimate. |
All tools are **read-only** and zero-config for public data. No keys, no signing, no accounts.
## Install
Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
```bash
git clone https://github.com/EMPangolin/avax-ops.git
cd avax-ops
uv venv
uv pip install -e mcp-server
```
## Use it from Claude Code
```bash
claude mcp add avax-ops -e AVAX_NETWORK=mainnet -- \
uv --directory /path/to/avax-ops run avax-ops-mcp
```
Then just ask:
> "Show me all my validators expiring in the next 30 days."
> "Is NodeID-7Xhw2mDx... meeting the ACP-267 uptime requirement?"
> "How much AVAX is left on my L1 validator's fee balance?"
Works the same in Claude Desktop, Cursor, or any MCP client (stdio transport, command `avax-ops-mcp`).
## Configuration
| Env var | Default | Meaning |
|---------|---------|---------|
| `AVAX_NETWORK` | `mainnet` | `mainnet` or `fuji` (testnet). |
## Example output
`validator_health` against a live Fuji validator:
```json
{
"nodeID": "NodeID-CRVEYUqnqNvCSBnWGQ8c1Fmg2qHZe581E",
"found": true,
"network": "fuji",
"connected": true,
"uptime_pct": 99.9958,
"uptime_meets_acp267_90pct": true,
"stake_AVAX": 1.0,
"end": "2026-08-18 05:30 UTC",
"days_remaining": 40.3
}
```
<!-- screenshot: add a Claude Code session screenshot here (agent calling the tools) -->
## Development
```bash
cd mcp-server
uv pip install --group pyproject.toml:dev # pytest, pytest-asyncio, ruff
pytest tests/ -q # unit tests (RPC layer mocked)
ruff check src tests && ruff format --check src tests
```
API field names (e.g. stake arriving as `weight` in nAVAX, not the legacy
`stakeAmount`) are verified against the live P-Chain API; test fixtures mirror
real captured responses.
## Roadmap
- **M1** — MCP server v0.1, read-only ops tools *(this release)*
- **M2** — Monitoring service + Telegram alerts (uptime, expirations, L1 balances)
- **M3** — AI diagnostics (`diagnose_node`), top-up estimator, L1 config helper
- **M4** — Web dashboard, docs, demo
## License
MIT
