# WhatConverts MCP Connector

Plain-language MCP server for **WhatConverts** leads, accounts, and attribution.

Same Claude OAuth + Cloud Run pattern as [meta-mcp-connector](https://github.com/devopsbrandmirchi/meta-mcp-connector). Ask about leads, sources, campaigns, and sales value in natural language.

## Features

- Live data from the [WhatConverts API](https://www.whatconverts.com/api/overview/)
- List agency accounts / profiles (master key) or query leads with a profile key
- Lead summary, daily trend, and breakdowns (source, medium, campaign, type, …)
- Search by email or phone; update quote / sales values
- Leads dashboard (`leads-dashboard.html`)
- Claude.ai OAuth when deployed to Cloud Run (`MCP_PUBLIC_URL`)

## Project structure

```
whatconverts-mcp-connector/
├── whatconverts_mcp_server.py   # MCP server + HTTP routes
├── whatconverts_tools.py        # All MCP tools (full API coverage)
├── whatconverts_api.py          # WhatConverts API client
├── whatconverts_oauth.py        # Claude-compatible OAuth provider
├── leads-dashboard.html
├── test-accounts.html
├── setup.html                   # How to get API Token + Secret
├── requirements.txt
├── Dockerfile
├── deploy-cloudrun.ps1
├── .env.example
└── .cursor/mcp.json
```

## Setup (local)

### 1. Install

```bash
cd whatconverts-mcp-connector
python -m venv .venv

# Windows
.venv\Scripts\activate

pip install -r requirements.txt
copy .env.example .env
```

### 2. Configure `.env`

```env
WHATCONVERTS_API_TOKEN=your_token
WHATCONVERTS_API_SECRET=your_secret
WHATCONVERTS_ACCOUNT_ID=
WHATCONVERTS_PROFILE_ID=
```

**Credentials**

1. Sign in at [app.whatconverts.com](https://app.whatconverts.com/)
2. **Profile key:** Tracking → Integrations → API Keys → Generate
3. **Master key (agency):** Master Integrations → API Keys
4. Copy Token + Secret into `.env`

Auth is HTTP Basic (`token:secret`). See `/setup` after starting the server.

### 3. Start the server

```bash
python whatconverts_mcp_server.py --http
```

| Endpoint | URL |
|----------|-----|
| MCP | `http://127.0.0.1:8001/mcp` |
| Leads dashboard | `http://127.0.0.1:8001/leads-dashboard` |
| Accounts test | `http://127.0.0.1:8001/test-accounts` |
| Setup guide | `http://127.0.0.1:8001/setup` |
| Health | `http://127.0.0.1:8001/health` |

### 4. Cursor MCP config

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "whatconverts": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}
```

Reload MCP in Cursor settings after starting the server.

## MCP tools

Full WhatConverts API coverage (accounts, profiles, leads, recordings, tracking, users, roles).

| Tool | Purpose |
|------|---------|
| `help_whatconverts` | Tool catalog |
| `get_integration_status` | Credential / API health |
| `list_accounts` / `get_account` | Agency accounts |
| `create_account` / `update_account` / `delete_account` | Account CRUD (`delete_*` needs `confirm=true`) |
| `list_profiles` / `get_profile` | Profiles under an account |
| `create_profile` / `update_profile` / `delete_profile` | Profile CRUD |
| `list_leads` | Filtered lead list (all documented filters) |
| `get_lead` / `search_leads` | Lead detail / find by email·phone·user_id |
| `create_lead` / `update_lead` | Create / edit leads |
| `get_leads_summary` / `get_daily_trend` / `get_leads_breakdown` | Analytics |
| `get_lead_recording` / `get_recording_file_meta` | Call recording URLs / file meta |
| `list_tracking_numbers` / `delete_tracking_number` | Call tracking numbers |
| `list_tracking_forms` / `delete_tracking_form` | Form tracking |
| `list_users` / `get_user` / `create_user` / `update_user` | Users (agency) |
| `list_roles` / `get_role` | Roles & permissions |
| `raw_api_request` | Escape hatch for any `/api/v1/` path |

## Example prompts

- How many leads this week?
- Break down leads by source for the last 14 days
- Show phone calls from google / cpc yesterday
- Find leads for email jane@example.com
- What's our sales value this month by campaign?

## Cloud Run

```powershell
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -Service "whatconverts-mcp"
```

Claude custom connector URL: `https://YOUR-SERVICE.run.app/mcp`  
Leave OAuth Client ID empty (DCR + CIMD).

## Security

- Never commit `.env`
- Rotate API Token/Secret if exposed
- Claude connector OAuth is separate from WhatConverts API auth