# Follow Up Boss connector for Claude

A tiny self-hosted MCP server that connects one Follow Up Boss account to Claude. You deploy your own copy, it holds your own API key, and Claude talks to it over a private link. No middleman, no per-task fees, full CRM access.

**Non-technical setup guide: [GUIDE.md](GUIDE.md)** (about 20 minutes, no coding)

## Deploy your own

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fthehillisrockin%2Ffub-claude-connector&env=FUB_API_KEY,MCP_SECRET&envDescription=FUB_API_KEY%20is%20your%20Follow%20Up%20Boss%20API%20key%20from%20Admin%20%3E%20API.%20MCP_SECRET%20is%20a%20long%20random%20password%20you%20make%20up%20(40%2B%20letters%20and%20numbers).)

After deploying, your connector URL is:

```
https://YOUR-APP.vercel.app/c/YOUR-MCP-SECRET/mcp
```

Add that as a custom connector in Claude (Settings > Connectors > Add custom connector).

## How it works

- Next.js App Router + [mcp-handler](https://www.npmjs.com/package/mcp-handler), stateless Streamable HTTP (no Redis)
- The URL path carries a long random secret; the API route checks it (constant-time) before anything runs, and wrong or missing secrets get a bare 404
- 25 curated tools cover the everyday CRM surface (people, leads via /events so action plans fire, notes, tasks, calls, texts, appointments, deals, pipelines, stages, users, action plans, custom fields, timeline)
- One `fub_api` raw tool covers the entire rest of the Follow Up Boss REST API
- DELETE calls are blocked unless you set `FUB_ALLOW_DELETE=1`
- New leads are created through `POST /v1/events`, the supported intake path, so Follow Up Boss deduplicates and fires lead flows exactly as if the lead came from a website

## Environment variables

| Name | Required | What it is |
|---|---|---|
| `FUB_API_KEY` | yes | Your Follow Up Boss API key (Admin > API > Create API Key) |
| `MCP_SECRET` | yes | A long random password you make up; becomes part of your private URL |
| `FUB_ALLOW_DELETE` | no | Set to `1` to let the raw tool make DELETE calls. Off by default |
| `FUB_X_SYSTEM` / `FUB_X_SYSTEM_KEY` | no | Only for registered Follow Up Boss partner systems |

## Local development

```bash
npm install
cp .env.example .env.local   # fill in FUB_API_KEY and MCP_SECRET
npm run dev
# connector at http://localhost:3000/c/YOUR-MCP-SECRET/mcp
```

## Security model

The secret link is the whole gate, so treat the full URL like a password. It is checked in constant time, invalid attempts get an anonymous 404, the internal `/api` path cannot be reached without the secret, and the MCP layer never sees the secret (the URL is normalized before it is handed off). Rotate by changing `MCP_SECRET` and redeploying; revoke everything by deleting the API key in Follow Up Boss.