使用说明

HubSpot MCP服务器

🚀 A完整 模型上下文协议（MCP） HubSpot CRM集成服务器，实现了所有21个MCP协议端点，支持多传输（HTTP、Streamable HTTP、STDIO）和灵活的端口配置。

✨ 特性

完整的MCP协议：所有21个端点（初始化、工具、资源、提示、通知、日志记录）
多运输支持：用于基于进程的通信的HTTP JSON-RPC、流式HTTP（SSE）、STDIO
全面的HubSpot集成：15多种用于联系人、公司、处理完整CRUD操作的工具
会话管理：具有超时和速率限制的基于UUID的会话
生产就绪：健康检查、指标、结构化日志记录、优雅关机
安全强化：OWASP合规性、非根执行、安全标头
多架构：AMD64和ARM64平台的Docker镜像
灵活的端口配置：可通过构建参数和运行时环境变量配置端口
高级会话管理：HTTP请求的基于Cookie和标头的会话持久性

📦 可用图像

注册表	图像	命令
GitHub容器注册表	`ghcr.io/sanketskasar/hubspot-mcp-server:latest`	`docker pull ghcr.io/sanketskasar/hubspot-mcp-server:latest`
Docker Hub	`sanketskasar/hubspot-mcp-server:latest`	`docker pull sanketskasar/hubspot-mcp-server:latest`

🚀 快速开始

先决条件

Docker已安装在您的系统上
HubSpot专用应用访问令牌(安装指南)

1.运行容器

GitHub容器注册表（推荐）：

docker run -d \
  --name hubspot-mcp-server \
  -p 3000:3000 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  -e TRANSPORT=http \
  --restart unless-stopped \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

Docker Hub：

docker run -d \
  --name hubspot-mcp-server \
  -p 3000:3000 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  -e TRANSPORT=http \
  --restart unless-stopped \
  sanketskasar/hubspot-mcp-server:latest

自定义端口配置：

# Use custom host port (e.g., 8080) while keeping container port as 3000
docker run -d \
  --name hubspot-mcp-server \
  -p 8080:3000 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  --restart unless-stopped \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

# Use custom container port (requires rebuild)
docker build --build-arg EXPOSE_PORT=8080 -t hubspot-mcp-server:custom .
docker run -d \
  --name hubspot-mcp-server \
  -p 8080:8080 \
  -e PORT=8080 \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here \
  hubspot-mcp-server:custom

2.验证安装

# Check health
curl http://localhost:3000/health

# Expected response:
# {"status":"healthy","uptime":...,"version":"1.0.0","sessions":0}

# Check MCP capabilities
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"test"}}}'

🔧 传输协议

HTTP传输（默认）

基于HTTP的标准JSON-RPC 2.0：

docker run -d -p 3000:3000 \
  -e TRANSPORT=http \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

可流式HTTP传输

服务器发送实时更新事件：

docker run -d -p 3000:3000 \
  -e TRANSPORT=streamable-http \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

# Connect to stream
curl -N -H "Accept: text/event-stream" http://localhost:3000/mcp/stream

STDIO传输

基于流程的沟通：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | \
docker run --rm -i \
  -e TRANSPORT=stdio \
  -e HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token \
  ghcr.io/sanketskasar/hubspot-mcp-server:latest

⚙️ 配置

环境变量

# Required Configuration
HUBSPOT_PRIVATE_APP_ACCESS_TOKEN=your_token_here

# Transport Configuration
TRANSPORT=http                    # http, streamable-http, stdio
PORT=3000
HOST=0.0.0.0

# Session Management
MAX_CONNECTIONS=100
SESSION_TIMEOUT=3600              # seconds

# Rate Limiting
RATE_LIMIT_TOOLS=60              # requests per minute
RATE_LIMIT_RESOURCES=30          # requests per minute  
MAX_CONCURRENT_REQUESTS=10       # per session

# Security
CORS_ORIGIN=*                    # "*", specific domain, or comma-separated
MAX_REQUEST_SIZE=10485760        # 10MB

# Operational
LOG_LEVEL=info                   # debug, info, warn, error
CONNECTION_TIMEOUT=30000         # milliseconds
GRACEFUL_SHUTDOWN_TIMEOUT=10000  # milliseconds

Docker Compose

基本配置：

version: '3.8'
services:
  hubspot-mcp-server:
    image: ghcr.io/sanketskasar/hubspot-mcp-server:latest
    container_name: hubspot-mcp-server
    ports:
      - "${HOST_PORT:-3000}:${CONTAINER_PORT:-3000}"
    environment:
      HUBSPOT_PRIVATE_APP_ACCESS_TOKEN: ${HUBSPOT_PRIVATE_APP_ACCESS_TOKEN}
      PORT: ${CONTAINER_PORT:-3000}
      TRANSPORT: http
      MAX_CONNECTIONS: 100
      SESSION_TIMEOUT: 3600
      RATE_LIMIT_TOOLS: 60
      RATE_LIMIT_RESOURCES: 30
      LOG_LEVEL: info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:${CONTAINER_PORT:-3000}/health"]
      interval: 30s
      timeout: 10s
      retries: 3

自定义端口配置：

# Run on custom ports
HOST_PORT=8080 CONTAINER_PORT=3000 docker-compose up -d

# Or set in .env file:
# HOST_PORT=8080
# CONTAINER_PORT=3000

🔧 会话管理

服务器提供 高级会话管理 对于在多个API调用之间维持状态的HTTP请求：

会话创建

会话在第一个请求时自动创建，并通过以下方式进行跟踪：

X-Session-ID标头：API客户端的主要方法
mcp会话Cookie：浏览器友好的会话持久性
请求正文参数：替代会话标识

会话持久性示例

使用标头（建议用于API客户端）：

# 1. Initialize and get session ID
response=$(curl -s -i -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {...}}')

# Extract session ID from X-Session-ID header
session_id=$(echo "$response" | grep -i "x-session-id" | cut -d' ' -f2 | tr -d '\r')

# 2. Use session ID in subsequent requests
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: $session_id" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'

使用授权承载人（替代方法）：

# Use session ID as Bearer token
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $session_id" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "resources/list", "params": {}}'

使用Cookie（浏览器兼容）：

# Save cookies and reuse them
curl -c cookies.txt -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {...}}'

# Subsequent requests with cookies
curl -b cookies.txt -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "resources/list", "params": {}}'

会话功能

自动创建：在第一次请求时透明地创建会话
多种持久化方法：标头、Cookie和正文参数
aiohttp。客户端会话兼容：针对Python HTTP客户端进行了优化
授权承载支持：替代会话识别方法
可配置超时：会话过期时间 SESSION_TIMEOUT 秒
重新连接支持：SSE传输允许会话重新连接
速率限制：工具和资源的每次会话费率限制
安全：SameSite保护，HTTPS可配置安全标志

🔑 HubSpot设置

第一步：创建私人应用

首选 HubSpot设置 → 集成 → 私人应用程序
点击 “创建私人应用程序”
配置所需范围：

范围	目的
`crm.objects.contacts.read`	读取联系信息
`crm.objects.contacts.write`	创建和更新联系人
`crm.objects.companies.read`	读取公司信息
`crm.objects.companies.write`	创建和更新公司
`crm.objects.deals.read`	阅读交易信息
`crm.objects.deals.write`	创建和更新交易
`crm.objects.owners.read`	读取所有者/销售代表信息

步骤2：生成令牌

首选认证标签
复制 访问令牌 （开始于 pat-...)
⚠️ 请确保此令牌安全！

步骤3：测试令牌

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://api.hubapi.com/crm/v3/objects/contacts?limit=1"

🛠️ 可用工具

服务器实现 15+HubSpot CRM工具 通过MCP协议：

联系人管理

工具	说明	参数
`get_contacts`	使用分页检索联系人	`limit`, `properties`, `after`
`create_contact`	创建新联系人	`email` （必填），其他属性
`update_contact`	更新现有联系人	`id`, `properties`
`search_contacts`	按查询搜索联系人	`query`, `properties`, `limit`
`get_contact_by_email`	通过电子邮件联系	`email`

公司管理层

工具	说明	参数
`get_companies`	使用分页检索公司	`limit`, `properties`, `after`
`create_company`	创建新公司	`name` （必填），其他属性
`update_company`	更新现有公司	`id`, `properties`
`search_companies`	按查询搜索公司	`query`, `properties`, `limit`

交易管理

工具	说明	参数
`get_deals`	检索分页交易	`limit`, `properties`, `after`
`create_deal`	创建新交易	`dealname` （必填），其他属性
`update_deal`	更新现有交易	`id`, `properties`
`search_deals`	按查询搜索交易	`query`, `properties`, `limit`

关系和活动工具

工具	说明	参数
`get_associations`	获取对象关系	`objectId`, `objectType`, `toObjectType`
`get_engagement_history`	获取活动时间表	`objectId`, `objectType`

📊 资源

8+可用实时资源：

hubspot://contacts -实时联系人数据库
hubspot://companies -实时公司数据库
hubspot://deals -实时交易渠道
hubspot://properties/contacts -联系人属性架构
hubspot://properties/companies -公司属性架构
hubspot://properties/deals -交易属性架构
hubspot://pipelines/deals -交易管道配置
hubspot://owners -销售代表/所有者信息

💡 提示

5+即用提示：

analyze_pipeline -交易渠道分析和优化
contact_research -深入接触和公司调研
lead_scoring -领导资格和评分
email_templates -HubSpot电子邮件模板生成
meeting_prep -会前研究和准备

📈 监测与健康

健康终点

端点	目的	响应
`GET /health`	基本健康检查	健康状态和正常运行时间
`GET /ready`	准备就绪探测	应用程序准备就绪
`GET /metrics`	Prometheus指标	性能指标
`GET /status`	详细状态	全面的服务器状态

示例用法

# Initialize session
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"client"}}}'

# List available tools
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"sessionId":"session-id"}}'

# Get contacts
curl -X POST http://localhost:3000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{
      "name":"get_contacts",
      "arguments":{"limit":5},
      "sessionId":"session-id"
    }
  }'

🔒 安全功能

非根执行 -容器以无特权用户身份运行
安全强化 -只读文件系统，功能下降
OWASP标头 -完成安全标头实现
会话管理 -具有超时的基于UUID的会话
速率限制 -可配置的每会话速率限制
输入验证 -全面的参数验证

🛠️ 发展

地方发展

git clone https://github.com/SanketSKasar/HubSpot-MCP-Server.git
cd HubSpot-MCP-Server

# Install dependencies
npm install

# Set up environment
cp env.example .env
# Edit .env with your HubSpot token

# Run with different transports
npm start -- --transport http
npm start -- --transport streamable-http  
npm start -- --transport stdio

# Run tests
npm test

# Build Docker image
docker build -t hubspot-mcp-server .

命令行选项

node src/server.js --help

Options:
  --transport, -t    Transport protocol (http|streamable-http|stdio)
  --port, -p         Port to listen on (default: 3000)
  --host, -h         Host to bind to (default: 0.0.0.0)
  --log-level        Logging level (debug|info|warn|error)
  --max-connections  Maximum concurrent connections
  --session-timeout  Session timeout in seconds

📊 演出

资源需求

环境	CPU	内存	并发会话
最小	0.25核	256MB	10
推荐	0.5核	512MB	50
高负载	1+核	1GB+	100+

监控

# Container metrics
docker stats hubspot-mcp-server

# Application metrics  
curl http://localhost:3000/metrics

# Performance testing
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/health

🚀 构建多建筑图像

# Setup buildx for multi-arch
docker buildx create --name multiarch --use

# Build for multiple architectures with default port
docker buildx build \
  --build-arg EXPOSE_PORT=3000 \
  --platform linux/amd64,linux/arm64 \
  --tag ghcr.io/sanketskasar/hubspot-mcp-server:latest \
  --tag sanketskasar/hubspot-mcp-server:latest \
  --push .

# Build with custom port configuration
docker buildx build \
  --build-arg EXPOSE_PORT=8080 \
  --platform linux/amd64,linux/arm64 \
  --tag your-registry/hubspot-mcp-server:custom-port \
  --push .

🤝 贡献

我们欢迎捐款！请看贡献.md 作为指导方针。

快速开始

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
进行更改并添加测试
确保所有测试通过： npm test
提交拉取请求

📜 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🔗 相关资源

模型上下文协议 -MCP官方规范
HubSpot API文档 -HubSpot CRM API
MCP协议规范 -MCP技术细节

📋 最新更新-版本1.0.0

🎉 生产发布功能

✅ 完整的多运输支持：HTTP、流式HTTP（SSE）和STDIO协议
✅ 灵活的端口配置：构建时间和运行时端口自定义
✅ 增强的会话管理：基于UUID的会话，具有全面的速率限制
✅ 多架构图像：原生支持AMD64和ARM64平台
✅ 生产硬化：OWASP安全合规性和全面监控
✅ 精简的代码库：删除了以生产为重点的开发组件

🌍 注册表可用性

GitHub容器注册表: ghcr.io/sanketskasar/hubspot-mcp-server:latest
Docker Hub: sanketskasar/hubspot-mcp-server:latest
多平台：两个注册表都支持AMD64和ARM64架构

🔧 关键能力

21个MCP协议端点：完全符合MCP协议2024-11-05版
aiohttp。客户端会话支持：优化了langchain_mcp_adapters的会话管理
15+HubSpot工具：联系人、公司和交易的完整CRUD操作
8+实时资源：实时访问HubSpot CRM数据和模式
5+即用型提示：商业智能和自动化模板
高级监控：健康、准备、指标和状态端点
企业安全：非根执行、安全标头、速率限制

🎯 内置于❤️ 对于MCP生态系统