Note: Coverage reporting will be available after setting up Codecov token and app integration.

HubSpot MCP Extended

Independent MCP server built directly from HubSpot's public OpenAPI specifications, providing comprehensive CRM automation with 106 tools including advanced workflows for invoices and line items.

Note: This is an independent, community-driven implementation and not affiliated with or endorsed by HubSpot. Built using HubSpot's official public OpenAPI specifications.

📜 Licensing

This software is source available with dual licensing:

• Free for non-commercial use (personal, educational, research, open source projects)
• Commercial license required for business/production use by for-profit organizations

See LICENSE for full terms and LICENSING.md for details on obtaining a commercial license.

🆕 Recent Improvements (v1.4.0)

• ✅ Dual Licensing Model: MIT for open source + Commercial license option for enterprise support
• ✅ Claude Desktop Parameter Compatibility: Fixed parameter name mismatch causing "Unable to infer object type" errors
• ✅ Line Items API Support: Added 11 new tools for complete invoice workflow functionality (95→106 tools)
• ✅ Smart Parameter Mapping: Automatic normalization of shortened parameter names (objtype/objectType, objid/objectId)
• ✅ Fixed macOS Compatibility: Deployment script now works natively on macOS without requiring GNU coreutils
• ✅ Docker Compose Integration: Optimized for persistent container with docker exec access
• ✅ Enhanced Deployment Verification: Automatic validation of tool count and JSON response integrity
• ✅ Cross-Platform Support: Works on macOS, Linux, and Windows with consistent behavior

🔮 Planned Enhancements

• 🔄 Rate Limit Handling: Automatic throttling and exponential backoff for HubSpot API limits (planned for v1.5.0)

🚀 Features

• 106 HubSpot Tools - Complete CRM functionality including contacts, companies, deals, tickets, quotes, invoices, and line items
• Docker Support - Containerized deployment for consistent environments
• Security First - Environment variable-based configuration, no hardcoded secrets, token redaction in logs
• Production Ready - Comprehensive error handling, secure logging, and testing
• TypeScript - Fully typed for reliability and developer experience

📋 Prerequisites

Essential (Required)

• Node.js (v20 or higher)
• npm (for dependency management)
• HubSpot Private App or Connected App with appropriate scopes and access token
• Claude Desktop or compatible MCP client

Optional (For Full Deployment)

• Docker and Docker Compose (only needed for ./deploy.sh)
• macOS/Linux/Windows (deployment script optimized for macOS)

💡 First time? You can skip Docker and use ./deploy-local.sh for quick testing!

🔄 Updating to Latest Version

For Existing Users

If you already have HubSpot MCP Extended installed and want to update to the latest version:

Option 1: Git Update (Recommended)

# Navigate to your project directory
cd hubspot-mcp-extended

# Pull the latest changes
git pull origin main

# Rebuild the project
npm install
npm run build

# If using Docker, rebuild the image
docker compose down
docker compose up -d --build

Option 2: Fresh Installation

# Backup your .env file first
cp .env .env.backup

# Remove old installation
rm -rf hubspot-mcp-extended

# Fresh clone and setup
git clone https://github.com/calypsoCodex/hubspot-mcp-extended.git
cd hubspot-mcp-extended
cp .env.backup .env
./deploy-local.sh  # or ./deploy.sh for Docker

Current Version: v1.4.0

Latest improvements:

• 106 tools (added 11 Line Items API tools)
• Enhanced parameter compatibility (objtype/objectType auto-mapping)
• Fixed macOS deployment script (no longer requires GNU coreutils)
• Improved Docker integration with persistent container

🚀 Quick Start

1. Clone Repository

git clone https://github.com/calypsoCodex/hubspot-mcp-extended.git
cd hubspot-mcp-extended

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env and add your HubSpot API token
# Make sure the variable name is exactly: HUBSPOT_ACCESS_TOKEN
vim .env  # or use your preferred editor

3. Deploy

Option A: Local Development (No Docker)

./deploy-local.sh

What this does:

• Installs dependencies
• Builds TypeScript
• Validates deployment (checks for 106 tools)
• No Docker required!

Option B: Docker Deployment (Production-Ready)

./deploy.sh

What this does:

• Builds Docker image
• Starts container with docker compose
• Validates deployment automatically
• Persistent container for quick docker exec access

4. Configure Claude Desktop

Update your Claude Desktop config at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

For Local Deployment:

{
  "mcpServers": {
    "hubspot-mcp-extended": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/hubspot-mcp-extended/build/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

For Docker Deployment:

{
  "mcpServers": {
    "hubspot-mcp-extended": {
      "command": "docker",
      "args": ["exec", "-i", "hubspot-mcp-extended", "node", "build/index.js", "--stdio"]
    }
  }
}

Important: Restart Claude Desktop after configuration changes.

5. Verify Installation

Quick Validation Commands

# 1. Verify deployment (no API key needed)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js --stdio | jq '.result.tools | length'
# Expected output: 106

# 2. Test tool execution (requires API key in .env)
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_v3_obj", "arguments": {"objectType": "contacts", "limit": "1"}}}' | node build/index.js --stdio
# Expected: Contact data or authentication error

After Successful Deployment

You should see:

• ✅ 106 tools available in Claude Desktop
• ✅ Tools appear in Claude's MCP tools list
• ✅ All HubSpot operations accessible through natural language

Docker-Specific Verification

# Verify the container is running (should show "Up" status)
docker compose ps

# Check logs (should show "106 tools")
docker compose logs

# Test the MCP server through Docker exec
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i hubspot-mcp-extended node build/index.js --stdio

💡 Usage Examples

Example 1: Search Contacts by Email

"Find all contacts with email domain @acme.com"

Claude will:

1. Use post-crm-v3-objects-objtype-search_search tool
2. Construct search with:
   • objectType: "contacts" (or objtype: "contacts" - both work!)
   • filterGroups with email filter

Example 2: Create an Invoice with Line Items

"Create an invoice for Acme Corp with:
- Item 1: Consulting Services - $500
- Item 2: Software License - $1,200
Total: $1,700"

Claude will:

1. Use post-crm-v3-objects-invoices_invoices to create invoice
2. Use post-crm-v3-objects-line_items-batch-create_create to add line items
3. Associate line items with invoice

Example 3: Batch Update Deals

"Update all deals in stage 'negotiation' to set close_date to end of month"

Claude will:

1. Search deals with post-crm-v3-objects-objtype-search_search
2. Batch update with post-crm-v3-objects-objtype-batch-update_update

Parameter Compatibility Note

Tools work with both parameter naming conventions:

• ✅ Short names: objtype, objid (from tool names)
• ✅ Full names: objectType, objectId (from schemas)

The server automatically maps between them, so Claude can use either form.

🛠️ Development

Project Structure

hubspot-mcp-extended/
├── src/              # TypeScript source code
│   ├── index.ts      # Main MCP server entry point
│   ├── tools/        # Tool implementations
│   └── schemas/      # OpenAPI schemas
├── scripts/          # Build and deployment scripts
├── docs/             # Documentation
│   └── specs/        # OpenAPI specification files
├── build/            # Compiled JavaScript (generated)
└── tests/            # Test files

Building from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode with auto-reload
npm run dev

# Verify tool count
node -e "const tools = require('./build/index.js'); console.log('Tools:', tools.hubspotTools?.length || 'Not available');"

Testing

# Run unit tests
npm test

# Run integration tests
npm run test:integration

# Test tool listing (works without API key - shows 106 tools)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js --stdio

# Test actual tool execution (requires valid API key in .env)
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_v3_obj", "arguments": {"objectType": "contacts", "limit": "5"}}}' | node build/index.js --stdio

# Test Docker deployment
./scripts/verify-docker-project.sh

# Automated Docker setup validation (NEW!)
./scripts/validate-docker-setup.sh

Environment Variables

• HUBSPOT_ACCESS_TOKEN (required): Your HubSpot API access token
• LOG_LEVEL (optional): Set logging verbosity (default: info)

🔄 Tool Regeneration

This server's tools are automatically generated from HubSpot's official OpenAPI specifications. To regenerate tools when HubSpot updates their APIs:

Quick Regeneration

npm run regenerate:all

Manual Step-by-Step

# 1. Ensure HubSpot specs are at known-good version (CRITICAL)
./scripts/ensure-hubspot-version.sh

# 2. Generate tools
npm run regenerate:specs
npm run regenerate:tools

# 3. Test and verify
npm run test:tools
./deploy.sh --allow-non-main

# 4. Update documentation
npm run regenerate:manifest

Current Status

• Tools: 106 (includes Line Items API - updated 2025-01-13)
• Source: HubSpot official OpenAPI specs
• Compatibility: Claude Desktop (names < 64 chars, parameter normalization)

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Create an Issue for bug reports
• Submit a Feature Request for enhancements
• Check Documentation for detailed guides

Built with ❤️ for the AI and automation community