# codexwatch MCP server

> Tracks OpenAI Codex usage from local logs to monitor tokens, API-equivalent costs, and plan limits.

- Repository: https://github.com/psychofict/codexwatch
- Page: https://hostedmcp.org/servers/psychofict/codexwatch
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 1.0.2

## Install

### Claude Code

```sh
claude mcp add codexwatch -- uvx codexwatch-cli
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "codexwatch": {
      "command": "uvx",
      "args": [
        "codexwatch-cli"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "codexwatch": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "codexwatch-cli"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"codexwatch","type":"stdio","command":"uvx","args":["codexwatch-cli"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "codexwatch": {
      "command": "uvx",
      "args": [
        "codexwatch-cli"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add codexwatch -- uvx codexwatch-cli
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.codexwatch]
command = "uvx"
args = ["codexwatch-cli"]
```

### Gemini CLI

```sh
gemini mcp add -s user codexwatch uvx -- codexwatch-cli
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "codexwatch": {
      "command": "uvx",
      "args": [
        "codexwatch-cli"
      ]
    }
  }
}
```

## FAQ

### How does codexwatch track my usage?

It reads the session logs that Codex already writes on your machine, meaning it does not need to open your login or make network requests to see your numbers.

### Does codexwatch double-count tokens if I have multiple sessions or machines?

No, it uses unique response IDs to ensure that forked sessions, subagents, or synced logs from other machines are only counted once.

### Can I use codexwatch with an AI agent?

Yes, it is an MCP server that allows agents like Claude Code or OpenAI Codex to check your usage, plan limits, and budget status mid-session.

### How are the prices calculated?

Prices are bundled from OpenAI's pricing pages; models without a published price are excluded from dollar totals rather than being counted as $0.