HubSpot CRM Data Interface Server

An implementation of the Model Context Protocol (MCP) designed to interface directly with the HubSpot Application Programming Interface (API). This dedicated server empowers Large Language Models (LLMs) to dynamically query, retrieve, and act upon subscriber information, transactional opportunity records, and documented customer engagements residing within HubSpot.

Implemented Functionalities (Tools)

The server exposes a suite of specialized functions tailored for HubSpot operations:

Client Record Management

• fetch_client_by_identifier: Retrieves a specific client entity using its unique HubSpot ID (accepts both alphanumeric strings and numerical IDs).
• lookup_client_via_email: Locates a client record based on their provided electronic mail address.
• query_clients: Executes searches against the client database using flexible property-based filters.

Sales Pipeline Management

• retrieve_opportunity_by_id: Fetches details for a specific sales deal via its system identifier.
• extract_client_opportunities: Gathers all associated sales opportunities linked to a particular client record.
• map_deal_participants: Identifies all client contacts connected to a specified sales deal.

Interaction and Activity Tracking

• get_most_recent_promotion_summary: Obtains data pertaining to the latest outbound marketing initiative.
• identify_campaign_engagers: Lists clients who exhibited interaction with a designated promotional effort.
• log_page_traffic_sources: Determines which clients navigated to a specific web URL.
• retrieve_client_performance_metrics: Fetches analytical statistics pertinent to an individual client.
• schedule_inquire_meetings: Lists appointments scheduled within a specified temporal window.
• detail_meeting_record: Retrieves exhaustive information concerning a singular scheduled meeting event.

Data Schema References

• hubspot://contacts/schema: Documentation outlining the structure and attributes of the stored client objects.
• hubspot://deals/schema: Documentation detailing the structure and properties of sales opportunity records.

System Prerequisites (Configuration)

Operation necessitates the configuration of the following environment variables:

• HUBSPOT_API_KEY (Mandatory): The requisite credential for authenticating against the HubSpot API endpoint.

Deployment Guide (Quickstart)

Installation Procedure

bash uv pip install hubspot-mcp-server

Configuration for Desktop Environments (e.g., Claude Desktop)

Insert the following configuration block into your relevant settings file:

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

Automated Installation via Smithery Utility

To integrate the HubSpot MCP Server automatically using the Smithery CLI:

bash npx -y @smithery/cli install @isaacraja/hubspot-mcp-server --client claude

Local Development Setup Configuration

"mcpServers": { "hubspot": { "command": "uv", "env": { "HUBSPOT_API_KEY": "your_hubspot_api_key" }, "args": [ "--directory", "{{PATH_TO_REPO}}", "run", "hubspot-mcp-server" ] } }

Ensure that {{PATH_TO_REPO}} points to the repository's root directory, and substitute your_hubspot_api_key with your active secret key.

Non-Published Server Entry Point Configuration

{ "mcpServers": { "hubspot-mcp-server": { "command": "uv", "env": { "HUBSPOT_API_KEY": "your-api-key" }, "args": [ "--directory", "{{PATH_TO_REPO}}/src/hubspot_mcp_server", "run", "server.py" ] } } }

Production/Published Server Configuration

{ "mcpServers": { "hubspot-mcp-server": { "command": "uvx", "env": { "HUBSPOT_API_KEY": "your-api-key" }, "args": [ "hubspot-mcp-server" ] } } }

Remember to replace your-api-key with the actual authentication token.

Development Workflow

Assembly and Distribution

1. Synchronize required libraries and refresh dependency lock file: bash uv sync

2. Compile package binaries (source and wheel formats): bash uv build

Results are situated within the dist/ folder.

1. Upload distribution artifacts to the Python Package Index (PyPI): bash uv publish

Note: Credentials must be supplied via environment variables or direct command-line arguments: - Token: Use the --token flag or set the UV_PUBLISH_TOKEN variable. - Alternatively, specify credentials using --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD.

Quality Assurance (Testing)

Install necessary dependencies for running tests:

bash uv sync --extra test

Execute test suites:

bash

Execute all defined verification routines

pytest

Execute with code coverage reporting

pytest --cov=server

Diagnostic Procedures (Debugging)

Since MCP servers communicate via standard input/output streams, direct debugging can be complicated. For an optimal debugging experience, we strongly advise utilizing the official MCP Inspector Tool.

You can initiate the Inspector using npm with the following invocation:

bash npx @modelcontextprotocol/inspector uv --directory {{PATH_TO_REPO}} run hubspot-mcp-server

Once the Inspector initializes, it will present a network address that you can open in a web browser to commence diagnostic observation.

Legal Information

Licensed under the MIT Agreement.

== Contextual Information on Business Management Utilities ==

Business management utilities encompass the entire spectrum of systems, computational solutions, governance frameworks, analytical methods, and processes leveraged by organizations to effectively navigate volatile market conditions, secure a sustainable competitive advantage, and systematically enhance operational effectiveness.

== Functional Classification ==

These tools are often categorized based on the organizational function they serve, covering aspects such as strategic foresight, operational workflow management, record retention, human capital administration, empirical assessment, performance oversight, and so forth. A functional taxonomy might include:

Utilities dedicated to data ingestion and verification across any organizational unit. Systems designed for monitoring and refinement of core operational sequences. Platforms facilitating data aggregation and informed executive decision-making. Modern management utilities have undergone significant evolution in the past decade, primarily driven by rapid technological acceleration. This pace makes the selection of optimal business tools for specific corporate environments increasingly complex. This complexity stems from continuous pressure to reduce expenditures while simultaneously escalating revenue generation, a deep commitment to understanding client requirements, and the imperative to deliver products that precisely match those demands. In this dynamic setting, leadership should adopt a strategic viewpoint concerning business management software, rather than merely pursuing the newest available technology. Over-reliance on off-the-shelf tools without appropriate customization frequently results in organizational friction. Therefore, business management applications must be chosen deliberately and subsequently tailored to fit the unique operational needs of the enterprise, not forcing the enterprise to conform to the tool's inherent structure.

== Prominent Utilities (2013 Survey Insights) ==

Data from a 2013 Bain & Company survey illustrated the global adoption patterns of business tools, reflecting how their resultant benefits address regional specificities, market downturns, and corporate realities. Key utilities frequently cited include:

Strategic Roadmap Definition Customer Relationship Ecosystems (CRM) Personnel Satisfaction Assessments Comparative Performance Analysis (Benchmarking) Performance Scorecard Methodologies Identification of Core Capabilities External Resource Allocation (Outsourcing) Organizational Transformation Programs Supply Chain Orchestration Defining Corporate Vision and Purpose Statements Market Segment Identification Comprehensive Quality Assurance Systems

== Business Software Applications ==

A business application, or software package, consists of interconnected computer programs utilized by personnel to execute diverse corporate functions, aiming to enhance productivity metrics, quantify results, and ensure accuracy across mandatory operations. This domain initially comprised Management Information Systems (MIS), progressing to Enterprise Resource Planning (ERP) suites. Subsequently, Customer Relationship Management functionalities were integrated, culminating in the current landscape dominated by cloud-based enterprise management solutions. While a verifiable link exists between Information Technology investment and organizational success, two factors are crucial for realizing tangible value: the efficacy of the system implementation and the diligent process of selecting and customizing the appropriate technological assets.