# TokenBar

> TokenBar is an open-source MCP server for developer tools. Check your remaining Claude Code, Codex and Copilot usage limits before a long task. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, Windows, Linux, iOS, Android, vscode, CLI
- **Website:** https://chaconlucas.github.io/tokenbar/
- **Repository:** https://github.com/chaconlucas/tokenbar
- **MCP Registry name:** io.github.ChaconLucas/tokenbar
- **Categories:** developer tools, productivity
- **Listing updated:** 2026-11-15

## About

An agent that is about to start a long job can ask this server how much of its 5-hour and 7-day allowance is left and when it resets, rather than discovering the cap mid-task. The registry entry names Claude Code, Codex, Copilot and Windsurf, and the project page also lists Cursor, Gemini, Kiro, GLM, Kimi, MiniMax and Amp, plus any tool that writes a small JSON file.

The MCP server is one part of a wider app. A desktop component collects the numbers and exposes a local JSON API on localhost port 41777, a CLI with a shell-prompt mode, and webhooks that fire at 80%, 95% and on reset to Slack, Discord, Home Assistant or any URL. Phones and watches only show what the computer sends over Wi-Fi.

Apps cover Mac, Windows, Linux, iPhone, Android, Apple Watch and Wear OS, with extras for VS Code, Raycast and Stream Deck. The README notes the Mac app is not yet notarized, so the first launch may need an override.

## Features

- **Budget check for agents:** Lets Claude Code, Codex and Cursor read remaining budget and reset time before a long task.
- **Local JSON API:** Serves usage on localhost:41777 to any script or app on the machine.
- **CLI:** Prints usage as JSON, for scripts, or as a shell prompt segment.
- **Threshold webhooks:** Sends events at 80%, 95% and reset.
- **Many displays:** Shows limits on desktop, phone, watch, VS Code, Raycast and Stream Deck.

## Good for

- Have an agent check its budget before a long refactor
- Show remaining usage in your shell prompt
- Get a Slack alert at 80% of a limit
- Watch limits on a phone or watch

## Install

### Claude Code (Terminal)

```sh
claude mcp add tokenbar -- npx -y https://github.com/ChaconLucas/tokenbar/releases/download/v0.5.3/TokenBar.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "tokenbar": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ChaconLucas/tokenbar/releases/download/v0.5.3/TokenBar.mcpb"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "tokenbar": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ChaconLucas/tokenbar/releases/download/v0.5.3/TokenBar.mcpb"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "tokenbar": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ChaconLucas/tokenbar/releases/download/v0.5.3/TokenBar.mcpb"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "tokenbar": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ChaconLucas/tokenbar/releases/download/v0.5.3/TokenBar.mcpb"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "tokenbar": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ChaconLucas/tokenbar/releases/download/v0.5.3/TokenBar.mcpb"
      ]
    }
  }
}
```

## FAQ

### Which AI tools does it track?

Claude Code, Codex, Copilot and Windsurf per the registry; the site also lists Cursor, Gemini, Kiro, GLM, Kimi, MiniMax and Amp.

### How do I install the MCP server?

Install the CLI first, then add the server to your tool; Cursor and VS Code have one-click installs and Claude Desktop uses the .mcpb bundle.

### Does it run locally?

Yes. The server uses stdio and usage is served from your own computer.

### Is the Mac app notarized?

Not yet, per the README, so macOS may block a browser-downloaded copy.

### Is TokenBar free?

Yes. TokenBar is open source, so you can use and self-host it for free.

### How do I add TokenBar to Claude Code?

Run this command in your terminal: claude mcp add tokenbar -- npx -y https://github.com/ChaconLucas/tokenbar/releases/download/v0.5.3/TokenBar.mcpb

### What are the best alternatives to TokenBar?

The closest alternatives to TokenBar are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.

---
Source: https://ai-powered.com/mcp/tokenbar
