Follow Up Boss MCP Server

A powerful Model Context Protocol (MCP) server for seamless integration with the Follow Up Boss real estate CRM API. This Python-based MCP server enables AI assistants to intelligently interact with your Follow Up Boss data, providing comprehensive access to contacts, leads, deals, and more.

🚀 Production Ready: Full CRUD operations, intelligent caching, duplicate detection, and automatic pagination for Follow Up Boss CRM data.

What is Follow Up Boss?

Follow Up Boss is a leading real estate CRM platform that helps agents and teams manage their leads, contacts, and transactions. This MCP server provides programmatic access to your Follow Up Boss account, allowing AI assistants to query, analyze, and manage your CRM data efficiently.

Key Features

🎯 Complete Follow Up Boss Integration

• 34 MCP Tools for comprehensive Follow Up Boss API access
• Full CRUD Operations: Create, Read, Update, Delete contacts and custom fields
• Dynamic Discovery: Find stages, custom fields, and sources by keyword
• Smart Date Filtering: Natural language dates ("last 7 days", "this month")
• Batch Operations: Update up to 100 contacts at once
• Duplicate Detection: FUB-compliant duplicate checking for Follow Up Boss contacts
• Intelligent Caching: 4.6x faster repeated queries with automatic cache invalidation
• Automatic Pagination: Seamlessly handle large Follow Up Boss datasets (1,000+ records)
• Rate Limiting: Built-in protection against API throttling

📊 Data Management

• Contacts/People: Full management with dynamic filtering by stage, source, user, tags, dates
• Custom Fields: Create, manage, and dynamically search custom fields
• Calls & Events: Access call logs and activity events from Follow Up Boss
• Deals & Tasks: Track deals and tasks within Follow Up Boss
• Pipelines & Stages: Work with Follow Up Boss sales pipelines
• Users & Teams: Manage Follow Up Boss team members

🔧 Advanced Capabilities

• Dynamic Discovery: AI discovers what data exists and how to query it
• Smart Date Filtering: "last 7 days", "this month", "older than 30 days"
• Batch Updates: Update multiple contacts in one operation (10x faster)
• Custom Processing: Execute Python code for data aggregation and analysis
• Enhanced Errors: Contextual error messages with helpful suggestions
• Comprehensive Logging: All operations logged to file
• Async Performance: High-performance async/await architecture
• Multi-Client Support: Works with Cursor, Claude Desktop, Cline, Continue.dev, and any MCP-compatible client

Installation

Prerequisites

• Python 3.9 or higher
• A Follow Up Boss account with API access
• Your Follow Up Boss API key (Get it here)

Quick Setup

1. Clone the repository:

   git clone https://github.com/benlaube/fub-mcp.git
   cd fub-mcp
   

2. Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure your Follow Up Boss API key:

   cp .env.example .env
   # Edit .env and add your FUB_API_KEY from Follow Up Boss
   

Configuration

This MCP server works with any AI client that supports the Model Context Protocol. Configure it once and use it with multiple AI assistants.

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "follow-up-boss": {
      "command": "python",
      "args": ["-m", "fub_mcp.server"],
      "cwd": "/path/to/fub-mcp",
      "env": {
        "PYTHONPATH": "/path/to/fub-mcp/src",
        "FUB_API_KEY": "your-follow-up-boss-api-key"
      }
    }
  }
}

For Other MCP Clients

See docs/guides/MULTI_CLIENT_SETUP.md for detailed setup instructions for:

• Cline (VS Code Extension)
• Continue.dev
• Other MCP-compatible clients

Usage Examples

Query Follow Up Boss Contacts

{
  "tool": "get_people",
  "arguments": {
    "limit": 100,
    "sort": "-created"
  }
}

Create a New Contact in Follow Up Boss

{
  "tool": "create_person",
  "arguments": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "source": "Website"
  }
}

Check for Duplicate Contacts

{
  "tool": "check_duplicates",
  "arguments": {
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Custom Follow Up Boss Query with Processing

{
  "tool": "execute_custom_query",
  "arguments": {
    "description": "Team performance report",
    "endpoints": [
      {"endpoint": "/people", "dateField": "created"},
      {"endpoint": "/calls", "dateField": "created"}
    ],
    "dateRange": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    },
    "processing": "result = {'total_leads': len(data['people']), 'total_calls': len(data['calls'])}"
  }
}

Available Tools (32 Total)

Follow Up Boss Contact Management

• get_people - List contacts from Follow Up Boss
• get_person - Get specific contact details
• create_person - Create new Follow Up Boss contact
• update_person - Update existing contact
• delete_person - Delete contact
• search_people - Search Follow Up Boss contacts
• check_duplicates - Find duplicate contacts

Follow Up Boss Custom Fields

• get_custom_fields - List all custom fields
• get_custom_field - Get specific custom field
• create_custom_field - Create new custom field
• update_custom_field - Update custom field
• delete_custom_field - Delete custom field

Follow Up Boss Activity Data

• get_calls, get_call - Phone call records
• get_events, get_event - Activity events
• get_notes, get_note - Contact notes
• get_appointments, get_appointment - Scheduled appointments

Follow Up Boss Sales Data

• get_deals, get_deal - Deal tracking
• get_tasks, get_task - Task management
• get_pipelines, get_pipeline - Sales pipelines
• get_stages, get_stage - Pipeline stages

Follow Up Boss User Management

• get_users, get_user - Team members
• get_me - Current user info

Advanced Querying

• execute_custom_query - Custom queries with Python processing

See docs/reference/AVAILABLE_TOOLS.md for complete tool documentation.

Performance & Efficiency

Intelligent Caching

• 4.6x faster repeated queries
• Automatic cache invalidation on data changes
• Configurable cache size (default: 1,000 entries)

Efficient Memory Usage

• 100 contacts: ~169 KB
• 1,000 contacts: ~1.65 MB
• Minimal memory footprint for large datasets

Smart Pagination

• Automatically handles Follow Up Boss API limit (100 records per request)
• Seamlessly fetches 1,000+ records with proper rate limiting
• No timeouts or throttling issues

Follow Up Boss API Integration

This server implements the complete Follow Up Boss API v1 specification:

• Full REST API support
• Automatic rate limiting and retry logic
• Comprehensive error handling
• Secure authentication via API keys

For more information about the Follow Up Boss API, visit: Follow Up Boss API Documentation

Testing

The server includes comprehensive tests covering all Follow Up Boss integration points:

# Run all tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# Run specific test category
pytest tests/test_crud.py

Test Results: 26/26 tests passing ✅

Documentation

📖 Quick Start

• QUICKSTART.md - Get started in 5 minutes
• docs/guides/QUICK_START_DISCOVERY.md - Using discovery features

📚 Guides

• docs/guides/CRUD_GUIDE.md - Complete CRUD operations guide
• docs/guides/DUPLICATE_CHECK_GUIDE.md - Duplicate detection
• docs/guides/CURSOR_SETUP.md - Cursor IDE setup
• docs/guides/MULTI_CLIENT_SETUP.md - Setup for different AI clients
• docs/guides/DEPLOYMENT_READY.md - Production deployment
• docs/guides/TESTING.md - Testing guide

🔧 Implementation Details

• docs/implementation/DYNAMIC_DISCOVERY_IMPLEMENTATION.md - Discovery system
• docs/implementation/SMART_DATE_FILTERING.md - Date filtering
• docs/implementation/IMPROVEMENTS_IMPLEMENTED.md - Latest updates (Nov 1, 2024)
• docs/implementation/CACHING_STRATEGY.md - Caching details

📋 Reference

• docs/reference/AVAILABLE_TOOLS.md - Complete tool reference
• docs/reference/TOOLS_SUMMARY.md - Tools summary

📁 More Documentation

See docs/ for complete documentation index.

Security & Best Practices

API Key Security

• ✅ API keys stored in environment variables only
• ✅ Never commit API keys to version control
• ✅ Secure authentication with Follow Up Boss API

Data Protection

• ✅ Sandboxed code execution for custom queries
• ✅ Input validation on all operations
• ✅ Rate limiting to protect Follow Up Boss API
• ✅ Comprehensive error handling

Contributing

Contributions to improve Follow Up Boss MCP server are welcome! Please feel free to submit issues or pull requests.

Support

For issues related to:

• This MCP Server: Open an issue
• Follow Up Boss API: FUB Support
• Model Context Protocol: MCP Documentation

License

MIT License - See LICENSE file for details

Acknowledgments

• Built for Follow Up Boss CRM platform
• Powered by Model Context Protocol (MCP)
• Inspired by JavaScript implementation
• Follow Up Boss API documentation: docs.followupboss.com

Made with ❤️ for the Follow Up Boss community

Follow Up Boss® is a registered trademark of Follow Up Boss, LLC. This project is not officially affiliated with or endorsed by Follow Up Boss.