mcp-hubspot: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

HubSpot MCP Server - A Model Context Protocol (MCP) server that enables AI assistants to interact with HubSpot CRM data. This is a Python-based MCP server designed for Docker deployment with built-in FAISS vector storage for semantic search and caching.

Development Commands

Installation and Setup

# Install in development mode
pip install -e .

# Run the server locally (requires HUBSPOT_ACCESS_TOKEN environment variable)
mcp-server-hubspot

# Or with explicit access token
mcp-server-hubspot --access-token YOUR_TOKEN

Docker Commands

# Build Docker image
docker build -t mcp-hubspot .

# Build multi-platform image
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t buryhuang/mcp-hubspot:latest --push .

# Run Docker container
docker run -e HUBSPOT_ACCESS_TOKEN=your_token -v /path/to/storage:/storage buryhuang/mcp-hubspot:latest

Testing

Tests are located in the tests/ directory:

• test_closed_tickets.py - Tests for closed ticket retrieval
• test_mcp_ticket_conversations.py - Tests for ticket conversation threads
• get_closed_ticket_conversations.py - Utility script for testing conversation retrieval

Run tests directly with Python (no test runner configured in pyproject.toml).

Architecture

Three-Layer Architecture

1. Server Layer (server.py)

   • MCP protocol implementation using mcp.server.stdio
   • Tool registration and routing
   • Initialization of dependencies (HubSpot client, FAISS manager, embedding model)
   • Single entry point that composes all handlers

2. Handler Layer (handlers/)

   • Domain-specific handlers extending BaseHandler
   • Each handler manages MCP tool schemas and executes tool calls
   • Handlers: CompanyHandler, ContactHandler, ConversationHandler, TicketHandler, SearchHandler, PropertyHandler
   • Responsible for FAISS storage integration via store_in_faiss_safely()