Forge Mcp

Forge MCP Server

一个远程 MCP 服务，可将 AI 助手连接到完整的 Salesforge 产品套件：Salesforge、Primeforge、Leadsforge、Infraforge、Warmforge 和 Mailforge。

基于 Model Context Protocol 构建，可与 Claude Desktop、Claude Code、Cursor、Windsurf 及任何兼容 MCP 的客户端配合使用。

支持的产品

Salesforge（78 个工具）- 账户额度和订阅、工作区、联系人、序列和子序列、潜在客户进度、邮箱、LinkedIn 账户、发件人资料、标签、加入前检查和确认、webhook、电子邮件验证、禁止联系名单

Primeforge（23 个工具）- 工作区、域名、邮箱、DNS 管理、预热邮箱、批量邮箱查询

Leadsforge（41 个工具）- 联系人搜索和计数、电子邮件/电话/LinkedIn 信息补全、公司关注者、相似对象搜索和免费预览、本地商家发现及所有者信息补全、筛选值查询

Infraforge（24 个工具）- 工作区、域名、邮箱、DNS、域名可用性、额度

Warmforge（15 个工具）- 工作区、邮箱、预热统计、投递测试、最新邮箱投递结果

Mailforge（23 个工具）- 工作区、域名、邮箱、DNS 管理、域名可用性、自动续订、域名伪装、转发

仅提供你要使用的产品的 API 密钥。未配置产品的工具不会显示。

快速开始

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "salesforge": {
      "url": "https://mcp.salesforge.ai/mcp",
      "headers": {
        "X-Salesforge-Key": "YOUR_SALESFORGE_API_KEY",
        "X-Primeforge-Key": "YOUR_PRIMEFORGE_API_KEY",
        "X-Leadsforge-Key": "YOUR_LEADSFORGE_API_KEY",
        "X-Infraforge-Key": "YOUR_INFRAFORGE_API_KEY",
        "X-Warmforge-Key": "YOUR_WARMFORGE_API_KEY",
        "X-Mailforge-Key": "YOUR_MAILFORGE_API_KEY"
      }
    }
  }
}

移除你不使用的产品对应的请求头行。保存后重启 Claude Desktop。

Claude Code

claude mcp add salesforge \
  --transport streamable-http \
  --url https://mcp.salesforge.ai/mcp \
  --header "X-Salesforge-Key: YOUR_SALESFORGE_API_KEY" \
  --header "X-Primeforge-Key: YOUR_PRIMEFORGE_API_KEY" \
  --header "X-Leadsforge-Key: YOUR_LEADSFORGE_API_KEY" \
  --header "X-Infraforge-Key: YOUR_INFRAFORGE_API_KEY" \
  --header "X-Warmforge-Key: YOUR_WARMFORGE_API_KEY" \
  --header "X-Mailforge-Key: YOUR_MAILFORGE_API_KEY"

Cursor

前往 Settings > MCP 并添加新服务：

• 名称： salesforge
• 类型： streamable-http
• URL： https://mcp.salesforge.ai/mcp
• 请求头： 与上文相同

获取 API 密钥

产品	获取位置
Salesforge	app.salesforge.ai > Settings > API
Primeforge	app.primeforge.ai > Settings > API
Leadsforge	app.leadsforge.ai > Settings > API
Infraforge	app.infraforge.ai > Settings > API
Warmforge	app.warmforge.ai > Settings > API
Mailforge	app.mailforge.ai > Settings > API

身份验证请求头

产品	请求头	格式
Salesforge	X-Salesforge-Key	YOUR_API_KEY
Primeforge	X-Primeforge-Key	YOUR_API_KEY
Leadsforge	X-Leadsforge-Key	YOUR_API_KEY
Infraforge	X-Infraforge-Key	YOUR_API_KEY
Warmforge	X-Warmforge-Key	YOUR_API_KEY
Mailforge	X-Mailforge-Key	YOUR_API_KEY

多个账户

如果你管理多个账户（例如，不同客户的账户），请添加单独的服务条目：

{
  "mcpServers": {
    "salesforge-client-a": {
      "url": "https://mcp.salesforge.ai/mcp",
      "headers": {
        "Authorization": "Bearer CLIENT_A_KEY"
      }
    },
    "salesforge-client-b": {
      "url": "https://mcp.salesforge.ai/mcp",
      "headers": {
        "Authorization": "Bearer CLIENT_B_KEY"
      }
    }
  }
}

每个条目都有自己的名称和 API 密钥。你的 AI 助手可以使用这两组工具，你可以在提示词中指定要与哪个客户协作。

使用示例

完成设置后，试着向你的 AI 助手提出以下请求：

• “列出我的 Salesforge 工作区”
• “显示工作区 X 中标记为‘enterprise’的联系人”
• “创建一个名为‘Q2 Outreach’的新序列”
• “列出序列 31086 中的潜在客户，并显示针对某个潜在客户执行的操作和条件”
• “显示子序列 31086 的父序列和已加入的联系人”
• “将这些联系人加入序列”
• “显示我的 Primeforge 域名”
• “在 Leadsforge 中搜索纽约 SaaS 公司的 CTO”
• “获取 Salesforge LinkedIn 页面的关注者，并查找他们的电子邮件”
• “在花费额度前，显示与 salesforge.ai 类似的公司”
• “查找阿姆斯特丹 10 公里范围内的牙医，并获取其所有者信息”
• “查看我的 Infraforge 额度余额”
• “显示我的邮箱预热统计”
• “显示 Warmforge 中最新投递结果为 100% 的邮箱”
• “列出我的 Mailforge 域名”
• “检查 example.com 在 Mailforge 上是否可用”

异步电子邮件验证

使用 start_email_validation 启动验证。在返回 HTTP 201 前，Multichannel 会解析并持久化候选联系人成员信息。selected 和 skipped.duplicate 是确切且受支持的计数：选择结果非空时返回 status: pending，选择结果为空时返回 status: failed 和 failureCode: validation_scope_empty。已省略并弃用旧版 strict 选项。保留返回的 validationJobID，并以约 10 秒的间隔轮询 get_validation_results。持续轮询，直到状态进入终态：completed、partially_completed 或 failed。在为联系人注册前，先检查轮询响应；该响应是验证结果的权威依据，终态计数具有权威性，失败的运行不得自动重新提交。

注册时，对已完成或部分完成的 validationRunId 使用 preflight_enrollments，检查预检结果，然后使用 confirm_enrollment_preflight。若要限制候选联系人，请提供非空的 validationStatuses；省略状态或将其设为空表示不限制状态，并会考虑该运行的所有候选联系人，包括未经验证的联系人。持久化的异步运行会依据所请求运行中已持久化的结果评估非空状态，而旧版已完成运行则会依据当前的 Salesforge 状态进行评估。部分完成的运行不会自动只选择成功的子集。

本地 HTTP MCP 测试仍会代理已部署的 Multichannel API。

发布依赖

内部发布顺序具有约束力：先部署 Multichannel 异步验证契约，再发布 Forge MCP。Forge MCP 不得再将 strict: false 作为发布变通方案。

项目结构

src/
├── index.ts              # stdio entry point
├── http.ts               # HTTP/SSE transport entry point
├── server.ts             # MCP server setup, tool registration
├── api-client.ts         # HTTP client for upstream APIs
├── client.ts             # legacy client
├── helpers.ts            # shared utilities
└── tools/
    ├── identity.ts       # API key validation
    ├── account.ts        # account credit balances and subscription
    ├── workspaces.ts     # workspace management
    ├── contacts.ts       # contact CRUD
    ├── mailboxes.ts      # mailbox and email operations
    ├── threads.ts        # primebox threads, labels, and LinkedIn replies
    ├── sequences.ts      # sequence lifecycle and lead progress
    ├── subsequences.ts   # subsequence triggers, parents, and members
    ├── nodes.ts          # sequence node management
    ├── branches.ts       # sequence branches
    ├── enrollments.ts    # contact enrollment
    ├── linkedin.ts       # LinkedIn connection and session management
    ├── tags.ts           # workspace tag discovery
    ├── sender-profiles.ts# sender profile management
    ├── validations.ts    # email validation
    ├── webhooks.ts       # webhook management
    ├── dnc.ts            # do-not-contact lists
    ├── custom-vars.ts    # custom variables
    ├── reference.ts      # action/condition type lookups
    ├── primeforge/       # domain, mailbox, workspace tools
    ├── leadsforge/       # search, enrichment, lookalike, followers, local business tools
    ├── infraforge/       # domain, mailbox, credit tools
    ├── warmforge/        # workspace, mailbox, placement test tools
    └── mailforge/        # workspace, domain, mailbox tools

自行托管

如果你更倾向于运行自己的实例：

npm install
npm run build
npm run start:http

服务器默认监听端口 3000。API 密钥通过每个请求的标头传递，而非作为环境变量传递。

HTTP 端点使用无状态 MCP POST 请求。不提供独立的 SSE 流：GET /mcp（以及 HEAD）会在分配 MCP 服务器前返回 405 Method Not Allowed。每请求创建的服务器和传输会在请求处理后、发生故障时，以及客户端在响应完成前断开连接时关闭。

诊断日志

默认以 JSON 行格式将日志写入 stderr，适用于容器日志收集。MCP stdio 输出仍专用于协议消息。HTTP 请求（包括 /health）会收到生成的 X-Request-Id 响应头，用于关联请求日志和上游 API 日志。

环境变量	默认值	用途
LOG_LEVEL	info	最低严重级别：debug、info、warn 或 error。Debug 级别会额外记录 MCP 设置耗时和上游响应头耗时。
SLOW_REQUEST_MS	3000	当 HTTP 请求或上游请求持续挂起达到此时长时，发出一条警告。不会取消请求或更改超时设置。
RUNTIME_LOG_INTERVAL_MS	10000	HTTP 进程指标的采集间隔：活动请求数、事件循环延迟/利用率、CPU 和内存。

如需更多详情，请运行 LOG_LEVEL=debug npm run start:http。无效设置会回退到默认值。排查超时问题时，请保持启用 info 或 debug，以便保留请求开始事件和进程指标。

• http.request.started 事件没有对应的 completed 或 aborted 事件，表示请求未完成，或进程在记录完成事件前停止。请求仍处于挂起状态（包括解析请求正文期间）时会发出 http.request.slow。
• upstream.request.slow 用于标识处于挂起状态的产品 API 调用；其耗时包括读取和解析响应。父级 requestId 将其关联到 HTTP 请求，upstreamRequestId 则用于区分多次 API 调用。
• runtime.metrics 可显示超时前后事件循环延迟、CPU、内存或请求数是否增加。事件循环阻塞也会延迟日志记录；阻塞结束后，停顿情况才会显现。
• 如果超时的健康检查没有对应的请求开始事件，也请检查代理/负载均衡器日志和容器重启情况。请求可能未到达 Express，也可能是进程无法运行。仅凭日志无法确定根本原因。

为避免记录 API 密钥和客户数据，结构化日志不会包含请求头、请求正文、查询字符串、上游路径以及错误消息/堆栈信息。在可用时，错误日志会包含类型、代码和 HTTP 状态。现有的 Node/Express 原生诊断信息仍可能单独显示。除 /health 和 /mcp 外，其他 HTTP 路由均标记为 other。

许可证

MIT

LinkedIn 回复

使用 get_thread 阅读对话，然后调用 reply_to_linkedin_thread，并传入 workspaceId、threadId、线程中 LinkedIn 消息所对应的发送方 LinkedIn accountId，以及 message。仅包含 LinkedIn 的线程无需邮箱 ID。该工具会调用现有的 Salesforge 公共 API，并返回创建的 LinkedIn 消息。

可选的 attachments 接受 filename、contentBase64 和可选的 contentType。若只发送附件，请传入空的 message，并至少提供一个附件。API 会验证支持的文件类型和大小限制。

Salesforge 账户和联系人管理

这些工具需要 multichannel-api #1068 和 salesforge-api #2795（SF-9461）中的公共 API 扩展。必须先部署相应的 API 变更，才能使用这些工具。

工具	行为
create_sender_profile、bulk_create_sender_profiles	创建资料，可选提供现有邮箱 ID 和 LinkedIn 账户 ID。批量创建接受 1–100 条记录，并分别报告每条结果。
connect_linkedin_account	连接 LinkedIn；将 skipSenderProfile: true 设为跳过自动创建发送者资料草稿。
get_linkedin_account、submit_linkedin_account_otp	检查连接状态并响应身份验证质询。
delete_contact、bulk_delete_contacts	删除一个联系人或最多 1,000 个联系人。批量删除会忽略工作区之外的 ID。
list_tags	通过分页、名称搜索和可选的区分大小写设置，查找标签 ID 和名称。

若要关联独立的 LinkedIn 账户，请使用 create_sender_profile 并提供其 linkedinAccountId。该账户必须属于此工作区，且尚未关联到其他发送者资料。

现有的 delete_sender_profile 工具也会删除其关联的 LinkedIn 账户。

Salesforge 邮箱和 LinkedIn 生命周期

这些工具需要 salesforge-api #2836 和 multichannel-api #1111（SF-10349），并依赖上述 SF-9461 API 扩展。必须先部署相应的 API 变更，才能使用这些工具。

工具	行为
disconnect_linkedin_account、reconnect_linkedin_account	管理会话，同时保留账户身份、历史记录、限制和发送者资料关联。
delete_mailbox	从 Salesforge 中移除邮箱，但不会删除其邮箱服务提供商处的电子邮件账户。
update_mailbox_connection_settings	即使邮箱已连接，也可更新 SMTP/IMAP 设置。至少为一种协议提供完整的 host、port、username 和 password 设置。未提供的协议保持不变。不支持 OAuth 邮箱。
update_sender_profile	使用 updates.linkedinAccountId 关联独立的 LinkedIn 账户。该资料必须尚未关联 LinkedIn 账户，或已关联同一账户。替换为其他账户会返回 409。省略或将 linkedinAccountId 设为 null 会保持关联不变；省略 mailboxIds 会保留邮箱。

没有独立的 LinkedIn 删除工具或电子邮件断开连接工具。现有的 delete_sender_profile 工具也会删除其关联的 LinkedIn 账户。