@hubspot/mcp-server

Exposes HubSpot's REST API endpoints as standardized MCP tools, translating HubSpot resource operations (contacts, deals, companies, etc.) into a schema-based function registry that MCP clients can discover and invoke. Uses MCP's tool definition protocol to wrap HubSpot API calls with standardized input/output schemas, enabling any MCP-compatible client (Claude, custom agents) to interact with HubSpot without direct API knowledge.

Manages HubSpot API authentication by accepting and validating API keys, automatically injecting credentials into outbound requests, and handling token refresh/expiration. Implements secure credential storage patterns appropriate for MCP server contexts, ensuring API keys are not leaked in logs or tool definitions while maintaining stateful authentication across multiple tool invocations.

Exposes HubSpot's custom property and field schema definitions as MCP tools, allowing LLM agents to discover available properties, their types, and validation rules for each object type. Implements schema introspection through MCP tool calls, returning property metadata (name, type, required, options for enums, etc.). Enables agents to validate property values before attempting to create or update objects.

Exposes HubSpot Workflows API as MCP tools for triggering custom workflows and automations. Implements workflow invocation through MCP tool calls, passing workflow input parameters and receiving execution status. Supports triggering workflows based on object changes or external events, enabling AI agents to orchestrate multi-step HubSpot automations.

Provides Create, Read, Update, Delete operations for HubSpot resources (contacts, deals, companies, tickets, etc.) through MCP tool definitions with schema validation. Each operation is exposed as a distinct MCP tool with input validation, error handling, and HubSpot-specific response normalization, allowing clients to perform standard data mutations without understanding HubSpot's API versioning or endpoint structure.

Translates natural search criteria (e.g., 'contacts with email domain @acme.com') into HubSpot's filter API syntax, supporting property-based filtering, date ranges, and relationship queries. Implements query builder patterns that map common search intents to HubSpot's filter language, handling edge cases like custom properties and enum-based fields without requiring clients to know HubSpot's filter syntax.

Automatically generates MCP tool schemas for HubSpot resources based on HubSpot's API definitions, exposing available operations, required/optional properties, and valid enum values. Implements schema introspection patterns that allow MCP clients to discover available tools and their input/output contracts without hardcoding, enabling dynamic tool registration and client-side validation.

Catches HubSpot API errors (rate limits, invalid properties, authentication failures) and translates them into human-readable error messages suitable for agent consumption. Implements retry logic for transient failures (rate limits, timeouts) and provides structured error responses that help agents understand what went wrong and how to recover.

Manages the MCP server initialization, configuration loading, and graceful shutdown. Implements server setup patterns that initialize HubSpot authentication, register available tools, and handle MCP protocol handshakes with clients. Supports configuration via environment variables, config files, or programmatic initialization, enabling flexible deployment in different environments (local development, Docker, serverless).

Enables querying HubSpot resource associations (e.g., contacts associated with a company, deals associated with a contact) through MCP tools that abstract HubSpot's association API. Implements relationship traversal patterns that allow agents to navigate HubSpot's object graph without understanding association type IDs or API endpoints, supporting multi-hop queries (e.g., contact → company → deals).

Translates HubSpot API errors into MCP-compatible error responses, providing clear error messages and error codes to LLM clients. Implements error categorization (authentication errors, rate limits, validation errors, not found, etc.), error recovery suggestions, and detailed error context. Handles HTTP status codes from HubSpot API and maps them to appropriate MCP error responses with actionable messages.

Exposes HubSpot search and filtering capabilities as MCP tools, allowing LLM agents to query HubSpot objects (contacts, companies, deals, tickets) using filter criteria. Implements filter construction, multi-field search, pagination support, and result sorting through MCP tool calls. Translates natural language search intents into HubSpot filter syntax and returns paginated result sets.