# Follow Up Boss MCP

A dedicated [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude / Cowork directly to your **Follow Up Boss** account through the official FUB REST API — no Zapier in the middle, no monthly task credits to run out.

Built for the *Morning Command Center* dashboard, but usable by any Claude conversation.

---

## What it can do

| Tool | What it does |
|------|--------------|
| `fub_test_connection` | Confirm the API key works (returns your account identity) |
| `fub_list_people` | Search/list leads & contacts (filter by stage, tag, source, agent) |
| `fub_get_person` | Full detail on one lead |
| `fub_stale_leads` | **Find going-cold leads** — no activity in N days (re-engagement pass) |
| `fub_list_deals` | Pipeline / deals |
| `fub_list_tasks` | Open (or completed) tasks |
| `fub_create_task` | **Schedule a follow-up** (e.g. "Text Jane in 3 days") |
| `fub_complete_task` | Mark a task done |
| `fub_create_note` | Add a note to a lead |
| `fub_log_call` | Log a call outcome |
| `fub_add_tags` | Tag a lead (merges, never overwrites) |
| `fub_list_users` | Find your FUB user id (needed to assign tasks) |
| `fub_list_smart_lists` | List Smart Lists (for future re-engagement workflows) |
| `fub_raw_request` | Escape hatch to any FUB endpoint |

---

## 1. Get your Follow Up Boss API key

In Follow Up Boss: **Admin → API → Create API Key**. Copy it somewhere safe — you'll paste it into the config below. (Auth is your key as the username with a blank password; the server handles that for you.)

## 2. Install

You need [Node.js 18+](https://nodejs.org). Then, in this folder:

```bash
npm install
```

Quick sanity check (no key needed):

```bash
npm test          # runs the offline test suite (17 checks)
node server.js --self-test   # lists the 14 tools
```

## 3. Connect it to Claude Desktop / Cowork

Open your Claude desktop config file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Add a `follow-up-boss` entry under `mcpServers` (keep any servers already there):

```jsonc
{
  "mcpServers": {
    "follow-up-boss": {
      "command": "node",
      "args": ["C:\\Users\\homes\\Claude\\Projects\\tucker\\follow-up-boss-mcp\\server.js"],
      "env": {
        "FUB_API_KEY": "paste-your-key-here",
        "FUB_SYSTEM": "",
        "FUB_SYSTEM_KEY": ""
      }
    }
  }
}
```

> The `args` path above already points at where this server lives on your machine. On macOS use forward slashes.

Then **fully quit and reopen Claude Desktop.** You'll know it worked when Claude can call `fub_test_connection` and returns your account.

## 4. First things to try

- "Use follow-up-boss to test the connection."
- "Show me my stale leads with no activity in 45 days."
- "List my open tasks that are overdue."
- "Schedule a follow-up task to text lead #123 tomorrow at 10am."

---

## Notes

- **Rate limits:** FUB allows ~250 requests per 10s window for registered systems (125 without `X-System` headers). The dashboard makes only a handful per load, so you're well within limits.
- **Security:** your API key stays local — it lives in your Claude config / environment and is sent only to `api.followupboss.com` over HTTPS. Don't commit a filled-in `.env` to git.
- **The dashboard:** once this server is connected, the Morning Command Center can be re-pointed from the Zapier path to these tools. That rewire is quick — just say the word and I'll update the artifact to call `follow-up-boss` directly.

## Files

- `server.js` — MCP wiring (stdio transport)
- `fub.js` — FUB API layer + tool definitions (SDK-free, unit-tested)
- `test.mjs` — offline test suite (mocks the API)
- `.env.example` — template for credentials