# @striderlabs/mcp-tmobile

MCP (Model Context Protocol) server for T-Mobile telecom account management. Automates T-Mobile account interactions using Playwright browser automation via Browserbase.

## Tools

| Tool | Description |
|------|-------------|
| `get_account_overview` | Get current plan, balance, and usage summary |
| `get_usage_details` | Get detailed data/call/text usage breakdown |
| `pay_bill` | Initiate a one-time payment |
| `get_bill_history` | View past bills and payment history |
| `check_upgrade_eligibility` | Check device upgrade eligibility for account lines |

## Setup

### Install

```bash
npm install @striderlabs/mcp-tmobile
```

### Environment Variables

```bash
# Required: T-Mobile credentials
export TMOBILE_USERNAME="your-email@example.com"
export TMOBILE_PASSWORD="your-password"

# Optional: Browserbase CDP URL for cloud browser automation
export BROWSERBASE_CDP_URL="wss://connect.browserbase.com?apiKey=your-key"
```

If `BROWSERBASE_CDP_URL` is set, the server connects to a Browserbase cloud browser. Otherwise, a local Chromium instance is launched.

Credentials can also be passed directly as tool arguments instead of environment variables.

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tmobile": {
      "command": "node",
      "args": ["/path/to/node_modules/@striderlabs/mcp-tmobile/dist/index.js"],
      "env": {
        "TMOBILE_USERNAME": "your-email@example.com",
        "TMOBILE_PASSWORD": "your-password",
        "BROWSERBASE_CDP_URL": "wss://connect.browserbase.com?apiKey=your-key"
      }
    }
  }
}
```

## Usage with MCP CLI

```bash
# Run directly
TMOBILE_USERNAME=user@example.com TMOBILE_PASSWORD=pass npx @striderlabs/mcp-tmobile

# With Browserbase
BROWSERBASE_CDP_URL=wss://... npx @striderlabs/mcp-tmobile
```

## Tool Examples

### Get Account Overview
```json
{
  "tool": "get_account_overview",
  "arguments": {}
}
```

### Get Usage Details
```json
{
  "tool": "get_usage_details",
  "arguments": {
    "line": "+15551234567"
  }
}
```

### Pay Bill
```json
{
  "tool": "pay_bill",
  "arguments": {
    "amount": 85.00
  }
}
```

### Get Bill History
```json
{
  "tool": "get_bill_history",
  "arguments": {
    "months": 3
  }
}
```

### Check Upgrade Eligibility
```json
{
  "tool": "check_upgrade_eligibility",
  "arguments": {}
}
```

## Browser Automation

This server uses Playwright to automate the T-Mobile account portal (`account.t-mobile.com`). The browser session is reused across tool calls within the same server process — login happens once and the session persists.

### Browserbase Integration

Connect via Browserbase for cloud-based browser automation:

```bash
export BROWSERBASE_CDP_URL="wss://connect.browserbase.com?apiKey=YOUR_API_KEY&enableProxy=true"
```

The server connects using Playwright's `chromium.connectOverCDP()`.

## Security Notes

- Credentials are never logged or stored beyond the current session
- Use environment variables rather than passing credentials in tool arguments when possible
- The `pay_bill` tool navigates to the payment page and returns details for review — it does not auto-confirm payments

## Development

```bash
git clone <repo>
cd mcp-tmobile
npm install
npm run build
npm start
```