HubSpot Extended MCP Server

A standalone MCP (Model Context Protocol) server that extends HubSpot functionality for post-call processing and pre-call preparation workflows.

Features

This server provides access to:

• Meeting Details: Retrieve complete meeting information including descriptions and properties
• Meeting Creation: Create new meetings with associations to deals and contacts
• Deal Meetings: Get all meetings associated with deals, with filtering and sorting
• Deal Notes: Get all notes associated with specific deals, sorted by timestamp
• Task Management: Create, retrieve, update, complete, and manage tasks with proper associations
• Task Lookup: Find tasks by deal or contact with fuzzy name matching support
• Overdue Tasks: Efficiently retrieve overdue tasks with owner filtering
• Meeting Search: Search meetings by keywords in descriptions
• Filtering & Sorting: Advanced filtering by outcome, exclude Calendly meetings, sort by date

Prerequisites

• Python 3.8 or higher
• A HubSpot account with access to create private apps
• Claude Desktop (or another MCP-compatible client)

Installation

1. Clone or Download the Repository

git clone <your-repo-url>
cd hubspotMcpExtended

Or download and extract the ZIP file to a location on your machine.

2. Install Python Dependencies

pip install -r requirements.txt

3. Set Up HubSpot Access Token

Create a HubSpot Private App:

1. Go to your HubSpot account
2. Navigate to Settings → Integrations → Private Apps
3. Click "Create a private app"
4. Give it a name (e.g., "MCP Server")
5. In the "Scopes" tab, select the following scopes:
   • crm.objects.contacts.read
   • crm.objects.deals.read
   • crm.objects.meetings.read
   • crm.objects.meetings.write
   • crm.objects.notes.read
   • crm.objects.tasks.read
   • crm.objects.tasks.write
6. Click "Create app" and copy the access token

Configure Environment:

Create a .env file in the project directory:

HUBSPOT_ACCESS_TOKEN=your_token_here
LOG_LEVEL=INFO

Replace your_token_here with the access token from your HubSpot private app.

4. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

On macOS:

open -a "TextEdit" ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "hubspot-extended": {
      "command": "python",
      "args": ["/FULL/PATH/TO/hubspotMcpExtended/main_fastmcp.py"],
      "cwd": "/FULL/PATH/TO/hubspotMcpExtended"
    }
  }
}

Important: Replace /FULL/PATH/TO/hubspotMcpExtended with the actual full path to where you downloaded/cloned this project.

5. Restart Claude Desktop

1. Quit Claude Desktop completely (Cmd+Q on macOS, or close all windows on Windows)
2. Reopen Claude Desktop
3. The HubSpot Extended server should now be available

Verify Installation

In Claude Desktop, try asking:

"Get the details for HubSpot meeting ID 12345"

If configured correctly, Claude will use the get_meeting_details tool from this server.

Available Tools

1. get_meeting_details

Retrieve complete meeting information.

Parameters:

• meeting_id (required): HubSpot meeting ID
• properties (optional): Array of specific properties to retrieve

2. create_meeting

Create a new meeting with associations to contacts and deals.

Parameters:

• title (required): Meeting title/name
• start_time (required): Meeting start time in ISO format (e.g., "2025-10-30T14:00:00Z")
• end_time (optional): Meeting end time in ISO format
• description (optional): Meeting description/body
• owner_id (optional): HubSpot owner ID for the meeting creator
• outcome (optional): Meeting outcome (SCHEDULED, COMPLETED, RESCHEDULED, NO_SHOW, CANCELED)
• location (optional): Meeting location
• contact_ids (optional): List of contact IDs to associate with the meeting
• deal_ids (optional): List of deal IDs to associate with the meeting
• meeting_type (optional): Type of meeting based on account meeting types
• internal_notes (optional): Internal team notes about the meeting

Examples:

• Create simple meeting: title="Client Call", start_time="2025-10-30T14:00:00Z"
• Create with associations: title="Sales Meeting", start_time="2025-10-30T14:00:00Z", deal_ids=["12345"], contact_ids=["67890"]

3. get_deal_notes

Get all notes associated with a specific deal.

Parameters:

• deal_id (required): HubSpot deal ID
• limit (optional): Number of notes to retrieve (default: 100)

4. create_task

Create a new task with associations to contacts and deals.

Parameters:

• title (required): Task title
• assigned_to_user_id (required): HubSpot user ID to assign to
• description (optional): Task description
• due_date (optional): Due date in ISO format
• priority (optional): HIGH, MEDIUM, or LOW
• contact_id (optional): Contact ID to associate with
• deal_id (optional): Deal ID to associate with
• task_type (optional): TODO, CALL, EMAIL, etc.

5. get_tasks

Retrieve tasks with optional filtering.

Parameters:

• owner_id (optional): Filter by task owner
• contact_id (optional): Filter by associated contact
• deal_id (optional): Filter by associated deal
• status (optional): Filter by task status
• limit (optional): Number of tasks to retrieve (default: 100)

6. get_task_details

Get detailed information for a specific task.

Parameters:

• task_id (required): HubSpot task ID
• properties (optional): Array of specific properties to retrieve

7. complete_task

Mark a task as completed.

Parameters:

• task_id (required): HubSpot task ID
• completion_notes (optional): Notes about the completion
• update_properties (optional): Additional properties to update

8. update_task

Update an existing task with new property values.

Parameters:

• task_id (required): HubSpot task ID
• title (optional): New task title
• description (optional): New task description/notes
• status (optional): Task status (NOT_STARTED, IN_PROGRESS, COMPLETED, WAITING, DEFERRED)
• priority (optional): Task priority (HIGH, MEDIUM, LOW)
• assigned_to_user_id (optional): HubSpot user ID to reassign task to
• due_date (optional): New due date in ISO format
• task_type (optional): Type of task (TODO, CALL, EMAIL, etc.)

Examples:

• Update title: task_id="123", title="Follow up with client"
• Change priority: task_id="123", priority="HIGH", status="IN_PROGRESS"
• Reassign task: task_id="123", assigned_to_user_id="456"

9. get_deal_meetings

Retrieve all meetings associated with a deal, with filtering and sorting.

Parameters:

• deal_id (required): HubSpot deal ID
• limit (optional): Number of meetings to return (default: 100)
• outcome_filter (optional): Filter by outcome (e.g., "COMPLETED", "SCHEDULED")
• exclude_calendly (optional): Exclude automated Calendly meetings
• sort_direction (optional): "DESCENDING" (newest first, default) or "ASCENDING"

10. get_overdue_tasks

Efficiently retrieve overdue tasks.

Parameters:

• owner_id (optional): Filter by task owner
• limit (optional): Number of tasks to return (default: 100)

11. search_meetings

Search meetings by keywords in descriptions.

Parameters:

• search_term (required): Term to search for
• limit (optional): Number of results (default: 10, max: 100)
• sort_direction (optional): "DESCENDING" (newest first, default) or "ASCENDING"

12. get_tasks_for_deal

Get all tasks associated with a specific deal using ID or fuzzy name matching.

Parameters:

• deal_id (optional): HubSpot deal ID
• deal_name (optional): Deal name for fuzzy search (e.g., "Delta Dental")
• include_completed (optional): Include completed tasks (default: False)
• limit (optional): Number of tasks to retrieve (default: 100)

Examples:

• Get pending tasks: deal_name="Delta Dental"
• Get all tasks by ID: deal_id="38702133148", include_completed=True

13. get_tasks_for_contact

Get all tasks associated with a specific contact using ID, name, or email.

Parameters:

• contact_id (optional): HubSpot contact ID
• contact_name (optional): Contact name for fuzzy search
• contact_email (optional): Contact email for exact match
• include_completed (optional): Include completed tasks (default: False)
• limit (optional): Number of tasks to retrieve (default: 100)

Examples:

• Get tasks by name: contact_name="John Smith"
• Get tasks by email: contact_email="john@example.com"
• Get all tasks by ID: contact_id="122794298695", include_completed=True

Configuration

Environment variables (set in .env file):

• HUBSPOT_ACCESS_TOKEN: Your HubSpot private app access token (required)
• LOG_LEVEL: Logging level (default: INFO, options: DEBUG, INFO, WARNING, ERROR)

Error Handling

The server handles common API errors:

• 401 Unauthorized: Invalid or expired token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource doesn't exist
• 429 Rate Limited: Automatic retry with exponential backoff
• 500+ Server Errors: Automatic retry with exponential backoff

Troubleshooting

Server Not Appearing in Claude Desktop

1. Check the config file path is correct
2. Verify Python path in config (try which python in terminal)
3. Check that all dependencies are installed
4. Look for errors in Claude Desktop logs (Help → View Logs)

API Errors

• 401 Unauthorized: Check your .env file has the correct HUBSPOT_ACCESS_TOKEN
• 403 Forbidden: Verify your private app has the required scopes
• Rate Limit: The server automatically retries, but you may need to reduce request frequency

Meeting Sort Issues

If meetings appear in the wrong order, ensure you've restarted Claude Desktop after updating the code.

Sharing with Others

To share this MCP server:

1. Package the project: ZIP the entire hubspotMcpExtended folder
2. Share the ZIP with other users
3. Provide instructions: Share this README with installation steps
4. Note: Each user needs their own HubSpot private app token