Follow Up Boss MCP Server

Give any AI agent full access to your Follow Up Boss CRM via natural language.

"Find all leads tagged 'Hot' assigned to Sarah and add a note saying I called them"
"Create a deal for Jane Smith in the Buyers pipeline worth $450,000"
"List all appointments this week and update the ones marked Pending to Confirmed"

160 tools across 25 modules — full coverage of the Follow Up Boss API v1.

---

What is this?

This is a Model Context Protocol (MCP) server that wraps the Follow Up Boss API. Connect it to Claude, Cursor, Windsurf, or any MCP-compatible AI client and your agent can read and write your entire FUB account using plain English.

Example prompts:

• "Find all people with the tag 'open house' who haven't been contacted in 30 days"
• "Create a task for every person in the 'New Lead' stage to send a follow-up email"
• "Show me all deals in the Listing pipeline worth more than $500k"
• "Add Sarah Johnson as a relationship contact (spouse) for contact ID 1234"
• "Send a bulk update setting stage to 'Active' for all people tagged 'webinar-2024'"

---

Tool Summary

Module	Tools	Description
People	17	Contacts, relationships, attachments
Appointments	15	Appointments, types, outcomes
Deals	14	Deals, custom fields, attachments
Templates	12	Email & text message templates
Groups	12	Groups, teams, team inboxes
Inbox Apps	10	Third-party inbox app integration
Automations	6	Automations 2.0 management
Ponds	6	Pond management and timeframes
Webhooks	6	Webhook subscriptions
Pipelines	5	Pipeline management
Custom Fields	5	Custom field definitions
Stages	5	Pipeline stage management
Tasks	5	Task management
Email Marketing	5	Campaigns and events
Notes	5	Lead notes
Action Plans	4	Action plan assignment
Calls	4	Call logging
Reactions	4	Reactions and threaded replies
Events	3	Lead events
Text Messages	3	SMS logging
Users	3	User/agent management
Smart Lists	2	Smart list access
Identity	2	Account identity
Convenience	5	Tag helpers, bulk update, email lookup
Meta	2	Server info and help
Total	160

Safe mode (default): 23 delete/destructive tools are disabled — 137 tools active. Set FUB_SAFE_MODE=false to enable all 160.

---

Prerequisites

1. Node.js 18+

node --version  # must be v18.0.0 or higher

2. Follow Up Boss API Key

1. Log in to your Follow Up Boss account
2. Go to Admin → API (or visit https://app.followupboss.com/2/api)
3. Copy your API key — it starts with fka_

3. (Optional) System Credentials

Some endpoints — automations, attachments, webhooks, inbox apps — are restricted to Registered Systems in FUB. To use these tools, you need:

• FUB_SYSTEM — your registered system name (e.g., "myapp")
• FUB_SYSTEM_KEY — your registered system key

Register your system at Admin → API → Registered Systems in your FUB account.

---

Installation

Run without installing (recommended)

# npx
npx @nerdsnipe-inc/follow-up-boss-mcp

# pnpm
pnpm dlx @nerdsnipe-inc/follow-up-boss-mcp

# bunx
bunx @nerdsnipe-inc/follow-up-boss-mcp

Install globally

npm install -g @nerdsnipe-inc/follow-up-boss-mcp
follow-up-boss-mcp

---

Connecting to AI Clients

Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "follow-up-boss": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/follow-up-boss-mcp"],
      "env": {
        "FUB_API_KEY": "fka_your_api_key_here"
      }
    }
  }
}

With system credentials:

{
  "mcpServers": {
    "follow-up-boss": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/follow-up-boss-mcp"],
      "env": {
        "FUB_API_KEY": "fka_your_api_key_here",
        "FUB_SYSTEM": "your-system-name",
        "FUB_SYSTEM_KEY": "your-system-key",
        "FUB_SAFE_MODE": "false"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (CLI)

claude mcp add follow-up-boss \
  -e FUB_API_KEY=fka_your_api_key_here \
  -- npx -y @nerdsnipe-inc/follow-up-boss-mcp

Or add manually to .claude/mcp.json in your project:

{
  "mcpServers": {
    "follow-up-boss": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/follow-up-boss-mcp"],
      "env": {
        "FUB_API_KEY": "fka_your_api_key_here"
      }
    }
  }
}

Cursor

Open Settings → MCP and add:

{
  "mcpServers": {
    "follow-up-boss": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/follow-up-boss-mcp"],
      "env": {
        "FUB_API_KEY": "fka_your_api_key_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "follow-up-boss": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/follow-up-boss-mcp"],
      "env": {
        "FUB_API_KEY": "fka_your_api_key_here"
      }
    }
  }
}

HTTP Transport (for Claude.ai Custom Connectors)

This server also supports Streamable HTTP with OAuth 2.1 for use as a Claude.ai custom connector or any remote MCP client.

FUB_API_KEY=fka_your_key PORT=3000 node dist/index.js --http

Or use the startHttp export in your own server:

import { startHttp } from '@nerdsnipe-inc/follow-up-boss-mcp';
await startHttp({ port: 3000 });

Any MCP-compatible client

Use the stdio transport command: npx -y @nerdsnipe-inc/follow-up-boss-mcp

---

Running from Source

git clone https://github.com/nerdsnipe-inc/follow-up-boss-mcp
cd follow-up-boss-mcp
npm install

# Development (no build needed)
FUB_API_KEY=fka_your_key npx tsx src/index.ts

# Build and run
npm run build
FUB_API_KEY=fka_your_key node dist/index.js

---

Tool Reference

People (17 tools)

Tool	Description
listPeople	List/search people with filtering by name, email, phone, tags, stage
createPerson	Create a new person/contact
getPerson	Get a single person by ID
updatePerson	Update an existing person
deletePerson	Delete (trash) a person by ID (safe mode blocked)
checkDuplicate	Check if a person already exists by email or phone
listUnclaimed	List unclaimed people in ponds
claimPerson	Claim an unclaimed person
createPersonAttachment	Attach an externally-hosted file to a person (requires system creds)
getPersonAttachment	Get a person attachment by ID
updatePersonAttachment	Update a person attachment
deletePersonAttachment	Delete a person attachment (safe mode blocked)
listRelationships	List relationships for a person
createRelationship	Create a relationship contact (Spouse, Brother, Partner, etc.)
getRelationship	Get a relationship by ID
updateRelationship	Update a relationship contact
deleteRelationship	Delete a relationship (safe mode blocked)

Appointments (15 tools)

Tool	Description
listAppointments	List appointments
createAppointment	Create an appointment
getAppointment	Get an appointment by ID
updateAppointment	Update an appointment
deleteAppointment	Delete an appointment (safe mode blocked)
listAppointmentTypes	List appointment types
createAppointmentType	Create an appointment type
getAppointmentType	Get appointment type by ID
updateAppointmentType	Update an appointment type
deleteAppointmentType	Delete an appointment type (safe mode blocked)
listAppointmentOutcomes	List appointment outcomes
createAppointmentOutcome	Create an appointment outcome
getAppointmentOutcome	Get appointment outcome by ID
updateAppointmentOutcome	Update an appointment outcome
deleteAppointmentOutcome	Delete an appointment outcome (safe mode blocked)

Deals (14 tools)

Tool	Description
listDeals	List deals with filtering
createDeal	Create a deal
getDeal	Get a deal by ID
updateDeal	Update a deal
deleteDeal	Delete a deal (safe mode blocked)
createDealAttachment	Attach a file to a deal (requires system creds)
getDealAttachment	Get a deal attachment by ID
updateDealAttachment	Update a deal attachment
deleteDealAttachment	Delete a deal attachment (safe mode blocked)
listDealCustomFields	List deal custom fields
createDealCustomField	Create a deal custom field
getDealCustomField	Get a deal custom field by ID
updateDealCustomField	Update a deal custom field
deleteDealCustomField	Delete a deal custom field (safe mode blocked)

Templates (12 tools)

Tool	Description
listTemplates	List email templates
createTemplate	Create an email template
getTemplate	Get an email template by ID
updateTemplate	Update an email template
mergeTemplate	Merge an email template with a person's data
deleteTemplate	Delete an email template (safe mode blocked)
listTextMessageTemplates	List text message templates
createTextMessageTemplate	Create a text message template
getTextMessageTemplate	Get a text message template by ID
updateTextMessageTemplate	Update a text message template
mergeTextMessageTemplate	Merge a text message template with person data
deleteTextMessageTemplate	Delete a text message template (safe mode blocked)

Groups (12 tools)

Tool	Description
listGroups	List all groups
listRoundRobinGroups	List round robin groups
createGroup	Create a group
getGroup	Get a group by ID
updateGroup	Update a group
deleteGroup	Delete a group (safe mode blocked)
listTeams	List all teams
createTeam	Create a team
getTeam	Get a team by ID
updateTeam	Update a team
deleteTeam	Delete a team (safe mode blocked)
listTeamInboxes	List all team inboxes

Inbox Apps (10 tools)

Tool	Description
inboxAppAddMessage	Add a message to an inbox app conversation (requires system creds)
inboxAppUpdateMessage	Update an inbox app message (requires system creds)
inboxAppAddNote	Add a note to an inbox app conversation (requires system creds)
inboxAppUpdateConversation	Update an inbox app conversation status (requires system creds)
inboxAppGetParticipants	Get participants of an inbox app conversation (requires system creds)
inboxAppCreateParticipant	Add a participant to a conversation (requires system creds)
inboxAppDeleteParticipant	Remove a participant from a conversation (requires system creds)
inboxAppInstall	Install an inbox app for a user (requires system creds)
inboxAppDeactivate	Deactivate an inbox app installation (requires system creds)
listInboxAppInstallations	List inbox app installations (requires system creds)

Automations (6 tools)

Tool	Description
listAutomations	List all Automations 2.0 automations (requires system creds)
getAutomation	Get an automation by ID (requires system creds)
listAutomationsPeople	List people in automations (requires system creds)
getAutomationPerson	Get an automation-person entry (requires system creds)
addPersonToAutomation	Add a person to an automation
updateAutomationPerson	Update a person's automation status

Ponds (6 tools)

Tool	Description
listPonds	List all ponds
createPond	Create a pond
getPond	Get a pond by ID
updatePond	Update a pond
deletePond	Delete a pond (safe mode blocked)
listTimeframes	List all timeframes

Webhooks (6 tools)

Tool	Description
listWebhooks	List all webhooks (requires system creds)
createWebhook	Create a webhook (requires system creds)
getWebhook	Get a webhook by ID (requires system creds)
updateWebhook	Update a webhook (requires system creds)
deleteWebhook	Delete a webhook (safe mode blocked, requires system creds)
getWebhookEvents	Get events for a webhook (requires system creds)

Pipelines (5 tools)

Tool	Description
listPipelines	List all pipelines
createPipeline	Create a pipeline
getPipeline	Get a pipeline by ID
updatePipeline	Update a pipeline
deletePipeline	Delete a pipeline (safe mode blocked)

Custom Fields (5 tools)

Tool	Description
listCustomFields	List all custom fields
createCustomField	Create a custom field
getCustomField	Get a custom field by ID
updateCustomField	Update a custom field
deleteCustomField	Delete a custom field (safe mode blocked)

Stages (5 tools)

Tool	Description
listStages	List all pipeline stages
createStage	Create a pipeline stage
getStage	Get a stage by ID
updateStage	Update a stage
deleteStage	Delete a stage (safe mode blocked)

Tasks (5 tools)

Tool	Description
listTasks	List tasks
createTask	Create a task
getTask	Get a task by ID
updateTask	Update a task
deleteTask	Delete a task (safe mode blocked)

Convenience (5 tools)

Tool	Description
removeTagFromPerson	Remove a single tag without affecting others
getPersonByEmail	Look up a person by email address
searchPeopleByTag	Find all people with one or more tags
bulkUpdatePeople	Update multiple people with the same changes
listAvailableTags	Discover tags used in your account

Email Marketing (5 tools)

Tool	Description
listEmEvents	List email marketing events
createEmEvent	Create email marketing events
listEmCampaigns	List email marketing campaigns
createEmCampaign	Create an email marketing campaign
updateEmCampaign	Update an email marketing campaign

Notes (5 tools)

Tool	Description
listNotes	List notes, optionally filtered by personId
createNote	Create a note on a person
getNote	Get a note by ID
updateNote	Update a note
deleteNote	Delete a note (safe mode blocked)

Action Plans (4 tools)

Tool	Description
listActionPlans	List all action plans
listActionPlansPeople	List people assigned to action plans
addPersonToActionPlan	Add a person to an action plan
updateActionPlanPerson	Update a person's action plan status

Calls (4 tools)

Tool	Description
listCalls	List calls
createCall	Log a call for a person
getCall	Get a call by ID
updateCall	Update a call record

Reactions (4 tools)

Tool	Description
getReactions	Get reactions for an item
createReaction	Create a reaction on an item
deleteReaction	Delete a reaction (safe mode blocked)
getThreadedReplies	Get threaded replies for an item

Events (3 tools)

Tool	Description
listEvents	List events with filtering
createEvent	Create a new event
getEvent	Get a single event by ID

Text Messages (3 tools)

Tool	Description
listTextMessages	List text messages (requires at least one filter)
createTextMessage	Log a text message from a third-party SMS system
getTextMessage	Get a text message by ID

Users (3 tools)

Tool	Description
listUsers	List all users/agents in the account
getUser	Get a user by ID
deleteUser	Delete a user (safe mode blocked)

Smart Lists (2 tools)

Tool	Description
listSmartLists	List all smart lists
getSmartList	Get a smart list by ID

Identity (2 tools)

Tool	Description
getIdentity	Get account information for the API key
getCurrentUser	Get the current authenticated user

Meta (2 tools)

Tool	Description
about	Get information about this MCP server
help	Get usage tips and examples

---

Example Prompts

Contact management:

• "Find all contacts tagged 'VIP' and add a note: 'Spoke with client, interested in Q1 listings'"
• "Create a new contact: John Doe, john@example.com, (555) 123-4567, tagged 'Buyer'"
• "Search for people with email domain @gmail.com in the Hot stage"

Deals and pipelines:

• "Show me all deals in the Seller pipeline worth over $800,000"
• "Create a deal for contact 5678 named 'Main St Listing' at $650,000 in stage 3"
• "Update deal 123 to set the price to $725,000 and close date to March 15"

Tasks and appointments:

• "Create a task for contact 1234: 'Send listing presentation' due tomorrow"
• "Schedule an appointment with Jane Smith on Friday at 2pm — type 'Buyer Consultation'"
• "List all appointments this week that don't have an outcome set"

Automation and follow-up:

• "Add everyone tagged 'webinar-march' to the Post-Webinar Follow-Up action plan"
• "Find all people in the 'New Lead' stage who have no tasks and create a call task for each"
• "Remove the tag 'do-not-contact' from person 9876"

Bulk operations:

• "Set the stage to 'Inactive' for all people tagged 'old-lead-2022'"
• "Find all people assigned to agent Sarah and list their current stages"

---

Environment Variables

Variable	Required	Default	Description
FUB_API_KEY	Yes	—	Your Follow Up Boss API key (starts with fka_)
FUB_SAFE_MODE	No	"true"	Set to "false" to enable delete/destructive tools
FUB_SYSTEM	No	—	Registered system name (for system-restricted endpoints)
FUB_SYSTEM_KEY	No	—	Registered system key (pair with FUB_SYSTEM)

---

Development

Scripts

npm run build          # compile TypeScript to dist/
npm run dev            # watch mode with tsx
npm test               # run all tests with vitest
npm run test:watch     # watch mode for tests
npm run test:coverage  # coverage report
npm run prepublishOnly # build + test (runs before npm publish)

Project structure

follow-up-boss-mcp/
├── src/
│   ├── index.ts          # server entry point (stdio + HTTP transport)
│   ├── client.ts         # HTTP client, config, error handling, translators
│   └── tools/
│       ├── people.ts
│       ├── deals.ts
│       ├── appointments.ts
│       ├── events.ts
│       ├── notes.ts
│       ├── calls.ts
│       ├── tasks.ts
│       ├── text_messages.ts
│       ├── users.ts
│       ├── smart_lists.ts
│       ├── action_plans.ts
│       ├── automations.ts
│       ├── templates.ts
│       ├── email_marketing.ts
│       ├── custom_fields.ts
│       ├── stages.ts
│       ├── appointments.ts
│       ├── webhooks.ts
│       ├── pipelines.ts
│       ├── groups.ts
│       ├── ponds.ts
│       ├── inbox_apps.ts
│       ├── reactions.ts
│       ├── convenience.ts
│       ├── identity.ts
│       └── meta.ts
├── tests/
│   ├── helpers.ts
│   ├── client.test.ts    # 59 tests
│   ├── server.test.ts    # 38 tests
│   └── tools/
│       ├── people.test.ts
│       ├── deals.test.ts
│       └── convenience.test.ts
├── bin/
│   └── follow-up-boss-mcp.js
├── dist/                 # compiled output
└── package.json

Adding a new tool

1. Find the module file under src/tools/ that matches the resource (or create a new one).
2. Add a ToolDef entry with name, description, inputSchema, and handler.
3. Export it from the module array and import it in src/index.ts.
4. Add a test in tests/tools/.
5. Run npm test to confirm green.

API translators

The FUB API uses non-standard field names in some places. The client.ts file includes translators that map natural MCP args to FUB's expected format:

• translateCallArgs — direction → isIncoming, notes → note
• translateDealArgs — personId → peopleIds[], value → price
• translateDealCustomFieldArgs — name → label, options → choices
• translateRelationshipArgs — relationshipType → type
• translateAppointmentArgs — startTime/endTime → start/end, appointmentTypeId → typeId, personId → invitees[]

---

Troubleshooting

Error	Cause	Fix
FUB_API_KEY is not set	Missing env var	Add FUB_API_KEY to your MCP config env block
FUB_API_KEY is set to a placeholder	Left the default value	Replace with your real API key from FUB admin
401 Unauthorized	Invalid or expired API key	Re-copy your key from FUB → Admin → API
403 Forbidden	Accessing system-restricted endpoint without system creds	Add FUB_SYSTEM and FUB_SYSTEM_KEY to your config
Tool not found	Safe mode is on	Set FUB_SAFE_MODE=false or use a non-delete tool
400 Bad Request on createDeal	Using value instead of price, or personId instead of peopleIds	The translators handle this automatically — check you're passing args correctly
429 Too Many Requests	FUB rate limit hit	Built-in retry with backoff — reduce request frequency if persistent
Server not showing in Claude Desktop	Config file syntax error or wrong path	Validate JSON, check file path for your OS

---

Contributing

Issues and PRs welcome. Please open an issue first for significant changes.

1. Fork the repo
2. Create a feature branch
3. Add tests for your change
4. Run npm test — all must pass
5. Submit a PR

---

License

MIT

---

Related

• Follow Up Boss API Docs
• Model Context Protocol
• GHL MCP Server — same pattern for GoHighLevel
• Lofty MCP Server — same pattern for Lofty CRM