使用说明

HubSpot 邮件 MCP 服务器

一个MCP（模型上下文协议）服务器，使Claude Code能够直接从文档文件中创建HubSpot营销电子邮件草稿.md 并且 .docx）。

特点/功能

📄 解析 Markdown（.md和 Word（.docx) 文件
🖼️ 自动提取图片并上传至HubSpot文件管理器
在HubSpot中使用默认模块创建营销电子邮件草稿
🔄 从文档中按正确顺序交错排列文本和图像
⚡ 优化了板块结构以防止Gmail截断
🎯 使用HubSpot的默认模块（@hubspot/rich_text， @hubspot/email_linked_image)
🎨 品牌指南支持，确保风格一致性（颜色、字体、间距、图片）
🛡️ 全面的错误处理和日志记录

它是如何运作的

MCP服务器会智能地解析您的文档，并创建一个结构良好的HubSpot电子邮件：

内容提取按顺序解析您的文档，同时追踪文本和图像
图片上传将所有图片上传到HubSpot文件管理器并获取CDN URL
模块创建为每个内容模块创建HubSpot模块：
- 文本块 → @hubspot/rich_text 模块
- 图像 → @hubspot/email_linked_image 模块
品牌造型/品牌设计应用您的品牌指南（如已配置）到模块和部分
段落优化将所有模块放在一个单独的部分中，以最大限度地减少HTML冗余并防止Gmail截断
电子邮件结构：
- 第0节所有内容（按顺序排列的文本+图片）均在单栏中显示
- 第一节页脚模块

这种方法避免了创建过多部分，这些部分可能会导致Gmail对超过102KB的电子邮件进行裁剪。

安装

先决条件

Python 3.10 或更高版本
拥有可访问私有应用的HubSpot账户
uv 包管理器（推荐）或 pip

安装依赖项

使用 uv （推荐）：

cd hubspot-email-mcp
uv sync

使用 pip：

cd hubspot-email-mcp
pip install -e .

HubSpot 设置

1. 创建一个私有应用

登录您的HubSpot账户
导航至设置 → 集成 → 私有应用
点击 创建一个私有应用
给它起个名字（例如，“邮件创建器MCP”）

2. 配置作用域

该应用需要以下权限范围：

内容：
- content （可读写营销邮件）
文件：
- files （对文件管理器的读写访问权限）

3. 获取API令牌

创建应用程序后，点击 显示令牌
复制令牌（以 pat-...）
安全地保存这个令牌——配置时需要用到它

配置

1. 创建配置文件

复制示例配置：

cp config.example.json config.json

2. 编辑配置

编辑 config.json 根据您的设置：

{
  "hubspot_api_key": "pat-na1-xxxx-xxxx-xxxx",
  "file_folder_path": "/email-images",
  "brand_guidelines_path": "brand-guidelines.json"
}

配置字段：

hubspot_api_key您的HubSpot私有应用令牌
file_folder_path在HubSpot文件管理器中上传图片的文件夹路径
brand_guidelines_path（可选）品牌指南JSON文件的路径，用于保持风格一致性

3. 无需模板！

这个MCP服务器使用HubSpot的默认模块来创建电子邮件，所以您可以 不需要自定义模板服务器自动：

创建拖放式电子邮件结构
使用来自设计管理器的标准HubSpot模块
构建优化部分以防止Gmail内容被截断

这个（或“该”） template_path 配置字段已被移除，因为不再需要。

4. 品牌指南（可选）

服务器支持品牌指南，以确保所有电子邮件的样式保持一致。创建一个 brand-guidelines.json 文件用于定义您品牌的颜色、字体、间距和图像风格。

📖 查看品牌指南参考文件.md 以获取所有可用字段的完整文档。

创建品牌指南文件

复制示例：

cp brand-guidelines.example.json brand-guidelines.json

编辑该文件并根据您的品牌进行定制。示例中包含了所有可用字段及其说明。

品牌指南结构

{
  "colors": {
    "primary": "#197FC4",
    "secondary": "#00a4bd",
    "text": "#23496d",
    "background": "#ffffff",
    "border": "#000000"
  },
  "typography": {
    "primaryFont": "Arial, sans-serif",
    "secondaryFont": "Arial, sans-serif",
    "headingOneSize": 28,
    "headingTwoSize": 22,
    "bodySize": 15,
    "linkColor": "#00a4bd",
    "linkUnderline": true
  },
  "spacing": {
    "sectionPaddingTop": "40px",
    "sectionPaddingBottom": "40px",
    "modulePaddingTop": "20px",
    "modulePaddingBottom": "20px"
  },
  "images": {
    "defaultWidth": 600,
    "maxWidth": "100%",
    "alignment": "center",
    "cornerRadius": 0,
    "addBorder": false,
    "borderWidth": 1,
    "borderColor": "#000000"
  },
  "buttons": {
    "backgroundColor": "#197FC4",
    "textColor": "#ffffff",
    "cornerRadius": 8,
    "fontSize": 16
  }
}

《What Gets Styled》（或可译为《风格之选》/《时尚焦点》）

当品牌指南配置完成后，服务器会自动应用：

文本模块：

字体和字号
文本颜色
模块填充（顶部/底部）

图像模块：

默认图像宽度
图像对齐（左/中/右）
圆角的半径
可选边框，支持设置颜色和宽度
模块内边距（顶部/底部）

部分/章节：

部分内边距（顶部/底部）
背景颜色

路径配置：

使用绝对路径： "brand_guidelines_path": "/absolute/path/to/brand-guidelines.json"
或者相对路径（相对于 config.json）： "brand_guidelines_path": "brand-guidelines.json"

与多个品牌/门户网站合作（推荐）

如果你需要管理多个HubSpot门户或品牌，最佳的方法是进行配置 多个MCP服务器 在Claude Desktop中。这将为您提供：

为每个门户单独设置API密钥
为每个品牌制定单独的品牌指南
切换时无需重启
门户之间的清晰隔离

示例设置：

为每个品牌创建单独的配置文件：

hubspot-email-mcp/
├── config-brand-a.json                # Brand A portal config
├── config-brand-b.json               # Brand B portal config
├── brand-a-guidelines.json      # Brand A styles
└── brand-b-guidelines.json     # ACME brand styles

config-brand-a.json：

{
  "hubspot_api_key": "pat-na1-xxxx-xxxx-xxxx",
  "file_folder_path": "/email-images",
  "brand_guidelines_path": "brand-a-guidelines.json"
}

config-brand-b.json：（可翻译为）品牌配置文件B.json

{
  "hubspot_api_key": "pat-na1-yyyy-acme-key",
  "file_folder_path": "/acme-email-images",
  "brand_guidelines_path": "brand-b-guidelines.json"
}

然后在Claude Desktop中配置多台服务器（详见下一节）。

单一品牌设置（备选方案）：

如果你只在一个门户网站工作，但偶尔想切换品牌指南：

{
  "hubspot_api_key": "pat-na1-xxxx",
  "file_folder_path": "/email-images",
  "brand_guidelines_path": "brand-guidelines.json"
}

更新 brand_guidelines_path 要切换样式，请重新启动Claude桌面程序。

Claude 桌面集成

单服务器设置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS/Linux) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows): （注：此处为原文的直接翻译，若需结合上下文或具体用途，可进一步解释为“（适用于Windows系统）：”或“（Windows平台）：”等）

{
  "mcpServers": {
    "hubspot-email": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/hubspot-email-mcp",
        "run",
        "hubspot-email-mcp"
      ],
      "env": {
        "HUBSPOT_EMAIL_MCP_CONFIG": "/absolute/path/to/config.json"
      }
    }
  }
}

多门户/品牌设置（推荐）

如果您需要使用多个HubSpot门户或品牌，请为每个门户配置一台服务器：

{
  "mcpServers": {
    "hubspot-email-brand-a": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/hubspot-email-mcp",
        "run",
        "hubspot-email-mcp"
      ],
      "env": {
        "HUBSPOT_EMAIL_MCP_CONFIG": "/absolute/path/to/config-brand-a.json"
      }
    },
    "hubspot-email-brand-b": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/hubspot-email-mcp",
        "run",
        "hubspot-email-mcp"
      ],
      "env": {
        "HUBSPOT_EMAIL_MCP_CONFIG": "/absolute/path/to/config-brand-b.json"
      }
    }
  }
}

使用方法：

当你要求Claude撰写一封电子邮件时，它会根据上下文了解你所针对的品牌/门户网站：

# For Brand A portal
Create a marketing email from newsletter.md for the Brand A portal

# For Brand B portal
Create a marketing email from announcement.docx for the Brand B portal

根据您的请求，Claude Code 将自动使用正确的服务器。

好处：

✅ 在不同门户之间切换时无需重启
每个门户都有自己的API密钥和品牌指南
✅ 能同时处理多个品牌的工作
✅ 清晰的分离与隔离

重要注意事项

使用 绝对路径 对于目录和配置文件两者
修改配置后重启Claude桌面版
如果服务器未显示，请检查Claude Desktop的日志： ~/Library/Logs/Claude/ (macOS) 或 %APPDATA%\Claude\logs\ （Windows）

使用方法

安装完成后，您可以在Claude Code中使用该工具：

基本用法

Create a marketing email from newsletter.md named "Monthly Newsletter"
with subject line "Your Monthly Update - January 2025"

使用DOCX文件

Create a marketing email from product-announcement.docx named
"New Product Launch" with subject "Introducing Our Latest Innovation"

示例工作流程

准备你的文件 (.md 或者 .docx（与）以下内容：
- 电子邮件内容（文本、标题、段落）
- 图像（嵌入或引用）

询问克劳德代码 创建电子邮件：

Create a HubSpot marketing email from /path/to/my-newsletter.md
named "Newsletter Q1" with subject "Quarterly Update"

克劳德将会:
- 解析文档
- 提取并上传任何图片到HubSpot
- 撰写电子邮件草稿
- 为您提供HubSpot邮件编辑器的网址
然后你可以:
- 在浏览器中打开该网址
- 在HubSpot中查看并编辑电子邮件
- 安排或发送电子邮件

文档格式指南

Markdown 文件 (`.md`)

# Heading 1

## Heading 2

Paragraph text with **bold** and *italic*.

![Alt text](./images/my-image.png)

- Bullet point 1
- Bullet point 2

图像参考：

本地图像： ![alt](./path/to/image.png) - 将被上传
外部图像： ![alt](https://example.com/image.png) - 将被跳过

DOCX 文件（`.docx`）

使用标准的Word格式（标题、段落、加粗、斜体）
嵌入的图像将自动提取
标题样式（标题1、2、3）将被转换为HTML标题

技术细节

使用的HubSpot模块

服务器使用来自设计管理器的HubSpot默认模块：

**@hubspot/rich_text**对于文本内容（段落、标题）
**@hubspot/email_linked_image**对于带有可选链接的图像
**@hubspot/email_footer**用于取消订阅的页脚

这些模块在所有HubSpot账户中默认可用，且无需任何自定义开发。

段落优化

为何这很重要：

Gmail会截断超过102KB的电子邮件
每个部分都会给电子邮件添加不必要的HTML冗余
多个部分可以快速推送超出限制的电子邮件

我们的方法：

将所有内容模块（文本+图片）放置在一个 单节（或单一区段）
仅在列布局发生变化时（例如，从1列变为2列）创建新部分
对于单栏电子邮件，这意味着总共只有两个部分：内容+页脚

未来增强/改进： 服务器可以通过检测布局变化，并仅在必要时创建新部分，来扩展以支持多列布局。

故障排除

服务器未在Claude桌面版中显示

检查路径是否为绝对路径（而非相对路径）
验证 uv 已安装： uv --version
检查Claude Desktop日志：
- macOS： ~/Library/Logs/Claude/
- Windows： %APPDATA%\Claude\logs\

API 错误

401 未授权：

请验证您的API密钥是否正确 config.json
确保私人应用程序未被停用

403 禁止访问：

检查私有应用是否具有所需的权限范围（content， files）

图片上传失败：

图像将被跳过，并发出警告
检查文件大小限制（HubSpot 对每个文件的大小限制为 50MB）
验证 file_folder_path 存在于您的文件管理器中

内容未显示

图片未显示：

检查图片是否已成功上传（查看日志中的成功消息）
验证CDN URL是否可访问
确保HubSpot账户已具备 files 范围已启用

文本格式问题：

服务器将Word样式转换为HTML（标题1 → <h1>等）
验证您的文档已应用了正确的标题样式

发展

运行测试

# Install dev dependencies
uv sync --dev

# Run tests (when implemented)
pytest

测试服务器

创建一个测试文档：

test.md: （文件名，可译为“测试文件.md”或保持原样，因为“.md”是Markdown文件的扩展名，通常不需要翻译）

# Test Email

This is a test email with an image.

![Test](./test-image.png)

然后使用Claude Code根据它创建一封电子邮件。

API 速率限制

HubSpot对其API设定了速率限制：

营销邮件API每10秒250个请求
文件API每10秒100个请求

服务器包含了针对速率限制（429错误）的基本错误处理。

安全注意事项

永远不要承诺 你的 config.json 包含真实API密钥的文件
安全地存储API密钥（在生产环境中使用环境变量）
该（或：这） config.example.json 提交是安全的（不包含真实密钥）

许可证

麻省理工学院（MIT）

支持

对于问题或疑问：

检查一下 MCP 文档
评论 HubSpot API 文档
在这个仓库中打开一个问题（或提交一个问题报告）