Looking for 10 early testers: HubSpot MCP Extended (Full CRM for AI Agents)

[jpsanchez]

Calling for 10 early adopters to battle‑test HubSpot MCP Extended — a secure, containerized MCP server exposing 100+ HubSpot endpoints (contacts, companies, deals, tickets, quotes, invoices, and line items). Built for Claude Desktop and agent frameworks.

Highlights:

• 106 tools with smart parameter mapping and complete invoice/line item coverage

• Works on macOS, Linux, and Windows; Docker-first; robust logging and error handling

• Verified JSON responses and automated tool-count validation

  If you work with HubSpot + AI agents and want early access, reply here or DM me. You’ll get a quick-start pack, direct support from me, and a shout‑out in the changelog.

  Who I’m looking for:

  • Builders using Claude Desktop or agent frameworks who want HubSpot to be first-class

  • Teams running real CRM automations and willing to share quick feedback

  • Must have a GitHub account

    What you’ll get:

    • Private access, direct support from me, and recognition in the release notes

      Interested?
      Comment “I’m in” or DM me “MCP Extended” and I’ll send the invite + onboarding.

[BérangèreL]

Hi @jpsanchez,
 

Thank you for sharing this exciting early access opportunity with the community!

It’s fantastic to see innovation happening at the intersection of HubSpot, AI, and agent frameworks.
 

For fellow members interested in exploring advanced automations with HubSpot and AI agents, this could be a valuable chance to provide input on a new integration before general release, and to directly impact its development.
 

A couple of reminders for everyone:
 

- Please remember to avoid sharing sensitive information in public comments when expressing interest; direct messaging is a good option for sharing project details privately.

- If you have any questions about how this tool aligns with HubSpot API best practices, feel free to raise them here so the broader community and our product experts can weigh in.

We look forward to hearing about the experiences of those who join the early testing and encourage testers to share feedback or tips that may help others considering similar solutions!
 

Thanks again for engaging the community and supporting collaborative innovation.

Have a great day!
Bérangère

[jpsanchez]

Aquí tienes el mensaje completo y pulido para responder en el hilo, adjuntando el README.md:

---

Thanks so much, Bérangère! Quick note on API alignment for HubSpot MCP Extended:

• Schemas: Tools are generated/validated directly from HubSpot’s official OpenAPI specifications, ensuring parity with object properties and parameters as APIs evolve.

• Auth & Security: Environment-based configuration for OAuth/Private App tokens; no hard-coded secrets. Full Dockerized deployment with verification steps.

• Tooling & Coverage:106 tools available, with automatic parameter normalization for robust compatibility. All responses are structured and validated for JSON integrity.

• Ops:Docker-first setup, health checks, comprehensive logging, and operational consistency across macOS, Linux, and Windows.

  All technical details and setup instructions are included in the README for transparency and easier auditing by the community—please feel free to review and raise any questions or suggestions. As best practices evolve, I’ll continue to document changes and add handling for things like rate limits and retry logic in upcoming updates. We’ll also share a public recap of key findings and best practices as testers join.

  Thanks again for your support!

  --------------------------

HubSpot MCP Extended
A secure, production-ready Model Context Protocol (MCP) server with 106 comprehensive HubSpot tools - Professional alternative to the basic HubSpot MCP with complete CRM functionality for AI assistants like Claude Desktop.

🆕 Recent Improvements (v1.3.1)
✅ 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.4.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.2.3
Latest improvements:

✅ Docker Compose Authentication: Fixed Step 3 setup issues
✅ RequestBody Support: All POST tools include proper body parameters (search, batch operations, etc.)
✅ Enhanced Troubleshooting: Automated validation scripts and better documentation
🔧 Quick Start
1. Clone Repository
bash git clone https://github.com/calypsoCodex/hubspot-mcp-extended.git cd hubspot-mcp-extended

2. Configure Environment
bash

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

⚠️ Critical: Your .env file must contain: HUBSPOT_ACCESS_TOKEN=your-hubspot-private-app-token

NOT API_KEY_PRIVATE_APPS or any other variable name.

Get your HubSpot token:

You can use either a Private App or Connected App:

Option A: Private App (Recommended for personal use)

Go to HubSpot Developer Account → Settings → Integrations → Private Apps
Create a new private app with required scopes (Contacts, Companies, Deals, etc.)
Copy the Access token (format: pat-na1-...)
Option B: Connected App (For OAuth-based integrations)

Go to HubSpot Developer Account → Settings → Integrations → Connected Apps

Complete OAuth flow to obtain access token

Use the OAuth access_token (managed by your application, not PAT format)

Paste the token in your .env file as HUBSPOT_ACCESS_TOKEN

📖 For detailed authentication instructions, see HubSpot Authentication Guide

⚠️ Important: Tool Listing vs Tool Execution
This server has two modes of operation:

🔍 Tool Listing Mode (No API Key Required)
Purpose: Validate deployment and show available tools
Works without: HubSpot API token
Command: echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js --stdio
Result: Shows all 106 available tools ✅
Use case: Deployment verification, Claude Desktop tool discovery
🚀 Tool Execution Mode (API Key Required)
Purpose: Make real calls to HubSpot API
Requires: Valid HUBSPOT_ACCESS_TOKEN in .env file
Example: Calling get_v3_obj to fetch contacts
Result: Real data from your HubSpot account ✅
Use case: Actual AI assistant functionality
Why this design? This allows you to verify the deployment works (106 tools listed) before configuring your API credentials, improving the setup experience.

🔧 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
3. Deploy
Option A: Quick Local Testing (No Docker Required) 🆕
Perfect for first-time users or quick validation:

# Quick local deployment and testing
./deploy-local.sh
What it does:

✅ Validates Node.js setup
✅ Installs dependencies
✅ Builds the project
✅ Verifies all 106 tools are available (tool listing)
✅ Provides next steps for Claude Desktop integration
Benefits:

🚀 No Docker required
⚡ Quick setup (2-3 minutes)
🔍 Perfect for testing before full deployment
Important: This validates that 106 tools are listed correctly. To actually use the tools (make real API calls), you must configure your HubSpot API token in the .env file as described in the next steps.

Option B: Full Docker Deployment
For production use with containerization:

# Build and verify the MCP server (includes 106 tools verification)
./deploy.sh

# If deployment completes successfully, start with Docker Compose
docker compose up -d
macOS Users: The deployment script has been optimized for macOS compatibility and will work without requiring additional tools like timeout.

Deployment Verification: The script automatically:

✅ Builds the TypeScript code
✅ Verifies exactly 106 tools are available
✅ Tests the MCP server locally
✅ Builds the Docker image
✅ Tests the Docker container
After successful deployment: bash

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

Important: The container is configured with command: ["sleep", "infinity"] to stay running for docker exec access.

Expected Status: Container should show "Up" (not "Restarting"). If restarting, check your .env file.

4. Connect to Claude Desktop
Configure Claude Desktop to use your MCP server. Choose the option that matches your Step 3 deployment method:

Location of Claude Desktop settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Option A: For Local Deployment (if you used deploy-local.sh)
{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/full/path/to/hubspot-mcp-extended/build/index.js", "--stdio"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-hubspot-private-app-token"
      }
    }
  }
}
Replace:

/full/path/to/hubspot-mcp-extended/ with your actual project directory
your-hubspot-private-app-token with your actual token
Option B: For Docker Deployment (if you used deploy.sh)
{
  "mcpServers": {
    "hubspot": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e",
        "HUBSPOT_ACCESS_TOKEN",
        "hubspot-mcp-extended",
        "node",
        "build/index.js",
        "--stdio"
      ]
    }
  }
}
Prerequisites:

Container must be running: docker compose ps
Set environment variable: export HUBSPOT_ACCESS_TOKEN=$(cat .env | grep HUBSPOT_ACCESS_TOKEN | cut -d'=' -f2)
Important Setup Notes:
Restart Claude Desktop after making these changes
Test connection by asking Claude to list your HubSpot contacts
Tool Count: This server provides exactly 106 tools - if you see fewer, check your deployment logs
🔍 Troubleshooting Authentication Issues:

If you get "OAuth token expired" errors, verify your environment:

# Check if container is running
docker compose ps

# Verify environment variable in your shell
echo $HUBSPOT_ACCESS_TOKEN

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

# If tools/list shows 106 tools but authentication still fails, check your HubSpot token:
# 1. Go to HubSpot Developer Account → Settings → Integrations → Private Apps or Connected Apps
# 2. Verify or regenerate your access token
# 3. Update your .env file with the new token
# 4. Restart Docker Compose: docker compose down && docker compose up -d

# Use the automated validation script for comprehensive troubleshooting:
./scripts/validate-docker-setup.sh
For all configurations:

Docker Required: Make sure Docker is running before starting Claude Desktop (Options 1 & 2)
Restart Claude: Restart Claude Desktop after adding this configuration
Verification: You can verify the connection by asking Claude to list your HubSpot contacts or companies
Tool Count: This server provides exactly 106 tools - if you see fewer tools, check your deployment logs
🔐 Security
All sensitive data is stored in .env file (git-ignored)
No hardcoded API keys or secrets
Secure environment variable loading
Production-grade Docker configuration
🧪 Testing
bash

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

🔧 Troubleshooting
Common Issues
First-time setup failing?
🆕 Try the local deployment first:

./deploy-local.sh
This skips Docker and helps identify basic setup issues.

"Expected 106 tools, got: 0"
Cause: Build failure or corrupted src/index.ts file

Solution:

# Check file integrity
wc -l src/index.ts  # Should show >2000 lines

# If corrupted, regenerate
npm run regenerate:all
npm run build
Note: Tool listing (showing 106 tools) should work WITHOUT an API key. If it doesn't, this indicates a build issue, not authentication.

"Tool shows but returns authentication error"
Cause: Confusion between tool listing (works without API key) vs tool execution (requires API key)
Solution:
✅ Tool listing works: You can see 106 tools without API key
❌ Tool execution fails: You need valid HUBSPOT_ACCESS_TOKEN in .env
Fix: Copy your HubSpot access token (from Private App or Connected App) to .env file
"HUBSPOT_ACCESS_TOKEN variable is not set"
Cause: .env file uses a different variable name (e.g., API_KEY_PRIVATE_APPS)
Solution: Ensure .env contains HUBSPOT_ACCESS_TOKEN=your-token exactly
"timeout: command not found" (macOS)
Status: ✅ FIXED - Deployment script now works natively on macOS
Previous Issue: Original deployment script required GNU coreutils
Current Solution: Uses Node.js-based timeout handling for cross-platform compatibility
"Cannot connect to the Docker daemon"
Cause: Docker Desktop is not running
Solution: Start Docker Desktop before running ./deploy.sh
Alternative: Use direct Node.js configuration (see above)
Container shows "Restarting" status
Cause: Missing or invalid HUBSPOT_ACCESS_TOKEN in .env file
Solution: Verify .env contains HUBSPOT_ACCESS_TOKEN=your-actual-token
Fix: Run docker compose down && docker compose up -d after fixing .env
Expected: Container should show "Up" status for docker exec to work
"Unable to infer object type from: {objectType}" - RESOLVED ✅
Status: 🎉 PERMANENTLY FIXED in v1.3.1
Previous Issue: Tools like contact search were failing with literal {objectType} in URL
Root Cause: Tool names use shortened parameter names (objtype, objid) to meet 64-char limit, but Claude Desktop inferred parameter names from tool names instead of schemas
Solution Applied:
Added automatic parameter mapping: objtype → objectType, objid → objectId
Both parameter naming conventions now work seamlessly
No breaking changes - maintains backward compatibility
For Users: If on v1.3.0 or earlier, update to v1.3.1+ to get the fix
"Tool count mismatch"
Expected: Exactly 106 tools should be available
Debug: Check deployment logs for JSON parsing errors
Verify Local: Run npm run build && node build/index.js --stdio manually
Verify Docker: Run echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i hubspot-mcp-extended node build/index.js --stdio
✅ "Invalid JSON input: a request body was expected, but none found" - RESOLVED
Status: 🎉 PERMANENTLY FIXED in v1.2.4
Previous Issue: Search tools (quotes/search, invoices/search) and batch operations were failing with JSON body errors
Root Cause: MCP server handler wasn't constructing requestBody correctly for POST requests
Solution Applied:
✅ Enhanced Handler: Automatically collects non-path parameters and builds JSON requestBody
✅ Parameter Addition: All search tools now have filterGroups, properties, limit, query, after, sorts
✅ Batch Tools Fixed: All batch operations now have proper inputs parameter with correct schema
✅ Verified Functionality: Confirmed working with real API calls (e.g., finding 18 contacts with hasCompletedTestOrienta = true)
If you encounter this error: Update to v1.2.4 or later - the issue is permanently resolved.

Development Mode
bash

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');"

📚 Documentation
Quick Start Guide - 5-minute setup for new users 🆕
API Coverage - Complete list of supported HubSpot APIs
Security Guide - Security configuration and best practices
Technical Guide - Architecture and technical details
Build Guide - Detailed build and deployment information
🛠 Available Tools
This server provides exactly 106 HubSpot tools across multiple CRM categories:

Core CRM Objects
Contacts - Create, read, update, delete contact records
Companies - Manage company information and associations
Deals - Track sales pipeline and deal progression
Tickets - Handle customer service requests
Quotes - Generate and manage sales quotes
Invoices - Create and manage invoice records
Line Items - Manage product line items for invoices and quotes (NEW in v1.3.0)
Advanced Features
Associations - Manage relationships between objects (v3 & v4 APIs)
Properties - Define and manage custom properties
Schemas - Work with custom object schemas
Search & Filtering - Advanced search capabilities with up to 10,000 results
Batch Operations - Process up to 100 records at once
See Tool Manifest for the complete list of all 106 tools.

💡 Usage Examples
Example 1: Search for Contacts by Email Domain
Ask Claude Desktop:

"Find all contacts with email addresses from @Calypso.top"
Claude will use: post-crm-v3-objects-objtype-search_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:

Use post-crm-v3-objects-invoices_invoices to create invoice
Use post-crm-v3-objects-line_items-batch-create_create to add line items
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:

Search deals with post-crm-v3-objects-objtype-search_search
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.

🔄 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
bash npm run regenerate:all

Manual Step-by-Step
bash

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

Generate tools
npm run regenerate:specs npm run regenerate:tools

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

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)