The HubSpot MCP Server provides a Python-based Model Context Protocol (MCP) interface to connect HubSpot data and capabilities with GenAI applications. It exposes a configurable server that can authenticate with HubSpot using API keys or OAuth credentials and handles MCP-style requests to interact with HubSpot data such as contacts, companies, deals, and marketing activities. The server is designed to be enterprise-ready with error handling and retry logic, and it supports asynchronous operation for improved performance when processing multiple MCP requests concurrently. Once running, you can send MCP queries and commands to retrieve, modify, or synchronize HubSpot resources through the generic MCP protocol used by LokiMC Universe repositories. Before use, ensure you have configured authentication credentials and any HubSpot-specific environment variables required by the server.

Typical use cases include: querying contacts or deals from HubSpot to feed into an AI assistant, syncing HubSpot data with external systems, or using the MCP interface to orchestrate sequences of HubSpot API operations as part of larger GenAI workflows.

Prerequisites:

• Python 3.8+ installed on your system
• pip available in your PATH
• Access to HubSpot API credentials (API Key or OAuth client credentials)

Install steps:

1. Create and activate a virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # On Windows use: venv\Scripts\activate

2. Install the HubSpot MCP Server package from PyPI: pip install hubspot-mcp-server

3. Alternatively, install from source (if you prefer the repository version): git clone https://github.com/LokiMCPUniverse/hubspot-mcp-server.git cd hubspot-mcp-server pip install -e .

4. Configure environment variables for authentication (see additional_notes for details):

   • Create a .env file or export variables in your environment: export HUBSPOT_API_KEY=your_api_key

     or for OAuth-based auth:

     export HUBSPOT_CLIENT_ID=your_client_id export HUBSPOT_CLIENT_SECRET=your_client_secret export HUBSPOT_REFRESH_TOKEN=your_refresh_token

5. Run the MCP server using the recommended command (provided in mcp_config): python -m hubspot_mcp

Tips and notes:

• Choose an authentication method that matches your HubSpot setup (API Key vs OAuth). If you are migrating to OAuth, ensure your redirect URI and consent configuration are correctly set in your HubSpot app.
• If your environment requires secure handling of credentials, consider using a secrets manager or a dedicated sample .env file with restricted access.
• The MCP server is designed to be used behind a reverse proxy or within a containerized environment for easier deployment and scaling.
• When debugging, enable verbose logging in your application or environment to capture request/response details for HubSpot API calls.
• Review rate limiting and retry behavior in the MCP server to align with HubSpot's API usage policies and your application's tolerance for latency.
• Ensure you expose the correct environment variables to the process running the MCP server; the env block in mcp_config lists commonly used keys.