# copilot-usage-mcp

An MCP server that exposes your GitHub Copilot premium request usage as a tool, broken down by model and cost.

## What it does

Provides a single MCP tool — `get_usage_current_month` — that fetches your Copilot premium request usage from the GitHub API and returns a formatted summary showing requests, cost per unit, gross amount, and net amount per model.

## Requirements

- Python 3.10+
- A GitHub Personal Access Token (PAT) with `manage_billing:copilot` scope

## Setup

1. **Install dependencies**

   ```bash
   pip install -r requirements.txt
   ```

2. **Set environment variables**

   ```bash
   export GITHUB_PAT=your_github_pat
   export GITHUB_USERNAME=your_github_username
   ```

3. **Run the server**

   ```bash
   python server.py
   ```

## MCP Configuration

To use with Claude Desktop or another MCP client, add this to your MCP config:

```json
{
  "mcpServers": {
    "copilot-usage-mcp": {
      "command": "python",
      "args": ["/path/to/copilot-usage-mcp/server.py"],
      "env": {
        "GITHUB_PAT": "your_github_pat",
        "GITHUB_USERNAME": "your_github_username"
      }
    }
  }
}
```

## Tool

### `get_usage_current_month`

Fetches the current month's Copilot premium request usage and returns a formatted breakdown by model.

**Example output:**
```
Copilot Premium Request Usage for octocat — 3/2026
──────────────────────────────────────────────────
  Model    : gpt-4o
  Requests : 42
  Per Unit : $0.04
  Gross    : $1.68
  You Paid : $1.68

──────────────────────────────────────────────────
Total Requests : 42
Total Gross    : $1.68
Total You Paid : $1.68
```

## License

MIT