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

Tool	Description
get_usage	Token counts and costs for a date range, broken down by period and model
list_sessions	Sessions with usage breakdown, grouped by period (top-N or all)
get_session_logs	Per-message logs for a session: timestamps, token counts, costs, roles

Setup

1. Install dependencies

pip install mcp

2. Configure

The server reads these environment variables:

Variable	Default	Description
OPENCLAW_AGENTS_DIR	~/.openclaw/agents/	Path to the OpenClaw agents directory containing session files

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.