openclaw-usage-mcp

MCP server that reads local OpenClaw session files for usage and cost data. No network calls or authentication required — it scans the JSONL session files directly from disk.

AI Agent  ──stdio──▶  MCP Server  ──reads──▶  ~/.openclaw/agents/*/sessions/*.jsonl

Tools

Related MCP server: AgentCost

Setup

1. Install dependencies

pip install mcp

2. Configure

The server reads these environment variables:

3. Register with your MCP client

mcporter (recommended with OpenClaw):

mcporter config add usage \
  --command python3 \
  --arg /path/to/server.py \
  --scope home

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "openclaw-usage": {
      "command": "python3",
      "args": ["/path/to/server.py"]
    }
  }
}

How it works

The server scans JSONL session files from the OpenClaw agents directory:

• Active sessions: ~/.openclaw/agents/*/sessions/*.jsonl

• Archived (reset) sessions: ~/.openclaw/agents/*/sessions/*.jsonl.reset.*

Each session file contains JSON lines with type: "session" headers, type: "message" entries (with usage/cost data on assistant messages), and type: "model_change" entries for model switches.

The server aggregates token counts and costs per model, per session, and per time period — returning the same structured output format the tools have always used.

Archived .reset.* files are included in scans, so usage from reset sessions is no longer invisible.

Running standalone

python3 server.py

Communicates over stdio using the MCP protocol.

Previous architecture

Earlier versions used the gateway's WebSocket RPC API with Ed25519 device authentication. That code (including device_auth.py) is preserved at tag v0.1.0-gateway-api.