# Anthropic Analytics MCP Server

A local [MCP](https://modelcontextprotocol.io) server that lets Claude (Desktop
and Code) answer plain-language questions about your Anthropic usage and spend —
both the **developer API platform** and the **Claude Enterprise** product (chat,
Claude Code, Cowork).

It wraps two Anthropic APIs behind one server:

- **Usage & Cost Admin API** (platform / developer API) — token usage and USD cost.
- **Enterprise Analytics API** — org adoption, per-user activity, and per-user
  usage across Claude, Claude Code, and Cowork.

API keys are never stored on disk. They live in **1Password** and are injected at
launch by the 1Password CLI (`op run`), which prompts for **Touch ID**.

## Tools

Platform (Admin key):

| Tool | Description |
|------|-------------|
| `get_cost_report` | USD cost over time, grouped by workspace/description. |
| `get_usage_report` | Token usage over time, grouped/filtered by model, workspace, key, tier. |
| `list_workspaces` | Map `wrkspc_…` ids to names. |
| `list_api_keys` | Map `apikey_…` ids to names/status. |

Enterprise (Analytics key):

| Tool | Description |
|------|-------------|
| `get_activity_summary` | Org-wide DAU/WAU/MAU, seat utilization, pending invites. |
| `get_user_activity` | Per-user engagement (messages, projects, Claude Code commits/PRs, Cowork sessions). |
| `get_skill_usage` | Skill adoption across surfaces. |
| `get_connector_usage` | Connector adoption across surfaces. |
| `get_chat_project_usage` | Conversation/user counts per chat project. |
| `get_user_cost` | Users ranked by USD spend (usage credits on seat plans). |
| `get_user_token_usage` | Users ranked by token usage. |
| `get_usage_by_subsidiary` | Rolls per-user usage up by **email domain** = subsidiary. |

> **Units note:** both APIs return cost `amount` values in **USD cents**. The
> server converts totals to dollars (`total_amount_usd`, `value_usd`); raw rows
> inside `data` remain in cents.

## Prerequisites

- macOS with [1Password CLI](https://developer.1password.com/docs/cli/) (`op`)
  installed and its desktop app integration enabled
  (1Password → Settings → Developer → *Integrate with 1Password CLI*).
- Python 3.10+.

## 1. Create the API keys

**Admin key** (platform usage/cost) — requires the org Admin/Primary Owner role:

1. Console → **Settings → Admin keys** (`https://platform.claude.com/settings/admin-keys`).
2. **Create Admin Key**. Value starts with `sk-ant-admin…`.

**Enterprise Analytics key** (Enterprise product) — requires the Primary Owner:

1. **Analytics → API keys** (`https://claude.ai/analytics/api-keys`).
2. Toggle **Access** on under *Analytics API*, then **+ Create key**.

> The Enterprise Analytics cost/usage endpoints reflect **usage credits** on
> seat-based plans; the engagement/adoption endpoints are the main value there.

## 2. Store both keys in 1Password

Create two items (any vault), each with the key in a field (e.g. `credential`):

- one for the Admin key
- one for the Enterprise Analytics key

Right-click each field → **Copy Secret Reference** to get its `op://…` path.

## 3. Point the launcher at your items

Copy the example and fill in your two references:

```bash
cp config.local.sh.example config.local.sh
$EDITOR config.local.sh
```

`config.local.sh` is git-ignored, so your vault/item names never get committed.

## 4. Install

```bash
./install.sh          # creates .venv and installs deps
```

Smoke test (triggers Touch ID, makes one live call):

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./run.sh
```

## 5. Connect the clients

Use the absolute path to `run.sh`.

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "anthropic-analytics": {
      "command": "/absolute/path/to/anthropic-analytics-mcp/run.sh"
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add anthropic-analytics --scope user /absolute/path/to/anthropic-analytics-mcp/run.sh
```

Restart Claude Desktop after editing its config.

## Usage examples

- "What was our total Anthropic API spend last month, by workspace?"
- "Show Enterprise usage by subsidiary for May."
- "Who are our top 10 users by Claude Code activity this week?"
- "What's our weekly active user count and seat utilization?"

## Notes & limits

- Data freshness: platform ~5 min; Enterprise Analytics refreshes ~every 4h and
  can revise for up to 30 days. For invoice-grade Enterprise totals, query dates
  ≥30 days old.
- Enterprise engagement data exists only from 2026-01-01 and for dates >3 days old.
- Cost API is daily-only and excludes Priority Tier (track that via usage).

## Troubleshooting

- `op: command not found` → install the 1Password CLI; enable the app integration.
- `invalid character in secret reference` → 1Password references can't contain
  `'` or `&`; rename the item.
- `401 invalid x-api-key` → wrong key type/role. Admin endpoints need an
  `sk-ant-admin…` key; Enterprise endpoints need the Analytics key.
- Desktop can't start it → ensure the `command` path is absolute and `run.sh` is
  executable. Logs: `~/Library/Logs/Claude/mcp*.log`.

## License

MIT — see [LICENSE](LICENSE).