Front MCP

Front MCP

通过支持本地 stdio 服务的 MCP 客户端使用 Front。搜索对话、管理联系人、发送消息、添加标签、分配任务并自动化收件箱工作流——提供 26 个工具和 172 项操作。

快速开始

1. 从 Settings > Developers > API tokens 获取 Front API 令牌。

2. 将此服务添加到 Claude Code 用户配置（~/.claude.json）顶层的 mcpServers 对象中，并保留任何已有的设置和服务。若要使用共享的项目配置，请改用 .mcp.json。请参阅 Claude Code 的 MCP 配置指南。

{
  "mcpServers": {
    "front": {
      "command": "npx",
      "args": ["-y", "@houst-com/front-mcp"],
      "env": {
        "FRONT_API_TOKEN": "your-front-api-token"
      }
    }
  }
}

3. 启动 Claude Code。现在即可使用 Front 工具。

需要 Node.js 20 或更高版本。该服务使用你自己的 Front 凭据在本地运行；无需使用 Houst 托管服务。请勿将 API 令牌纳入版本控制；共享的 .mcp.json 文件应使用 "FRONT_API_TOKEN": "${FRONT_API_TOKEN}"，并在启动 Claude Code 的环境中设置该变量。

工作流示例

搜索对话：

“搜索有关账单问题的 Front 对话”

查看会话：

“获取对话 cnv_abc123 中的消息”

管理联系人：

“列出联系人，并找到电子邮件为 [email protected] 的联系人”

添加标签并分配任务：

“给对话 cnv_abc123 添加 'urgent' 标签，并将其分配给队友 tea_xyz”

起草回复：

“为对话 cnv_abc123 创建一条草稿回复，说明我们明天会跟进”

OAuth 设置（推荐）

与 API 令牌相比，OAuth 支持自动刷新令牌，安全性也更高。

1. 在 Settings > Developers > OAuth apps 中创建 Front 应用。
2. 将重定向 URI 设置为 https://localhost:9876/callback。
3. 启用 MCP 服务所需的资源权限（Read、Write、Delete、Send）。
4. 保存应用——从 OAuth 功能中复制 Client ID（而不是 Settings 中的 App secret）。
5. 创建 ~/.front-mcp/config.json：

{
  "auth": {
    "method": "oauth",
    "oauth": {
      "client_id": "your-client-id",
      "client_secret_env": "FRONT_MCP_OAUTH_SECRET",
      "redirect_port": 9876,
      "scopes": []
    }
  }
}

6. 配置 Claude Code：

{
  "mcpServers": {
    "front": {
      "command": "npx",
      "args": ["-y", "@houst-com/front-mcp"],
      "env": {
        "FRONT_MCP_AUTH_METHOD": "oauth",
        "FRONT_MCP_OAUTH_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

7. 运行 npx @houst-com/front-mcp auth 进行身份验证（将打开浏览器）。
8. 令牌会经过加密并存储在本地（AES-256-GCM，权限为 0600）。

身份验证 CLI

front-mcp auth            # Start OAuth flow
front-mcp auth --status   # Check auth state (no token values shown)
front-mcp auth --clear    # Remove stored tokens
front-mcp --version       # Show version
front-mcp --help          # Show usage

Front 权限

MCP 服务需要具备与你想要使用的操作相对应的 Front API 权限：

权限	用途
Read	所有列出、获取和搜索操作
Write	create、update、assign、add、merge、reply
Delete	delete、remove 操作
Send	messages.create、messages.reply

对于 OAuth，请在 Front 应用的 Features > OAuth > Resource permissions 下配置这些权限。 对于 API 令牌，请在创建令牌时设置权限。

工具参考

工具	操作
accounts	list, get, create, update, delete, list_contacts, add_contact, remove_contact
analytics	create_export, get_export, create_report, get_report
channels	list, get, update, validate, create, list_for_teammate, list_for_team
comments	list, get, create, update, list_mentions, reply
contact_groups	list, create, delete, list_contacts, add_contacts, remove_contacts
contact_lists	list, create, delete, list_contacts, add_contacts, remove_contacts
contact_notes	list, create
contacts	list, get, create, update, delete, merge, list_conversations, add_handle, remove_handle
conversations	list, get, search, create, update, delete, assign, list_events, list_followers, add_followers, remove_followers, list_inboxes, add_link, remove_links, list_messages, update_reminders, add_tag, remove_tag
custom_fields	list_for_accounts, list_for_contacts, list_for_conversations, list_for_inboxes, list_for_links, list_for_teammates
drafts	list, create, create_reply, update, delete
events	list, get
inboxes	list, get, create, list_channels, list_conversations, list_access, grant_access, revoke_access
knowledge_bases	list, get, create, update, list_categories, list_articles, get_article, create_article, update_article, delete_article, get_category, create_category, update_category, delete_category
links	list, get, create, update, list_conversations
message_template_folders	list, get, create, update, delete, list_children, create_child
message_templates	list, get, create, update, delete
messages	get, create, reply, import, receive_custom, get_seen_status, mark_seen
rules	list, get, list_for_teammate, list_for_team
shifts	list, get, create, update, list_teammates, add_teammates, remove_teammates
signatures	list, get, update, delete, create_for_teammate, create_for_team
tags	list, get, create, update, delete, list_children, create_child, list_conversations
teammate_groups	list, get, create, update, delete, list_inboxes, add_inboxes, remove_inboxes, list_teammates, add_teammates, remove_teammates, list_teams, add_teams, remove_teams
teammates	list, get, update, list_conversations, list_inboxes
teams	list, get, add_teammates, remove_teammates
token_identity	get

完整参考（含每项操作的策略等级）请参阅 docs/TOOL_REFERENCE.md。

策略引擎

每项操作都会归入一个等级，并设有默认决策：

等级	默认决策	示例
read	允许	list, get, search
write	确认	create, update, assign
destructive	拒绝	delete, remove

写入操作需要两步确认：首次调用会返回提示词，第二次调用时传入 confirm: true 执行操作。破坏性操作默认拒绝。

自定义策略

创建 ~/.front-mcp/policy.json：

{
  "defaults": {
    "read": "allow",
    "write": "allow",
    "destructive": "confirm"
  },
  "overrides": [
    { "tool": "conversations", "action": "delete", "decision": "deny" },
    { "tool": "tags", "action": "*", "decision": "allow" }
  ]
}

优先级顺序：特定操作 > 工具通配规则 > 等级默认值。

安全模型

• 强制使用 HTTPS — 绝不回退到 HTTP
• 令牌加密 — 使用 AES-256-GCM 和 PBKDF2 密钥派生
• 文件权限 — 令牌文件权限为 0600（仅所有者可读写）
• 输出清理 — 可配置在大模型查看数据前对字段进行脱敏
• 日志脱敏 — 从所有日志输出中脱敏敏感字段
• 策略引擎 — 破坏性操作默认拒绝，写入操作需要确认
• 标准输出不含机密 — 标准输出仅用于 MCP 协议
• 最少依赖 — 使用原生 fetch、Node.js crypto，并固定精确版本

环境变量

变量	必需	描述
FRONT_API_TOKEN	是（OAuth 除外）	Front API 令牌
FRONT_MCP_AUTH_METHOD	否	oauth 或 api_token（默认：api_token）
FRONT_MCP_OAUTH_SECRET	是（使用 OAuth 时）	OAuth 客户端密钥
FRONT_MCP_LOG_LEVEL	否	error、warn、info、debug（默认：info）
FRONT_MCP_POLICY_FILE	否	自定义策略 JSON 文件的路径

限制

• 仅支持 stdio 传输——v1 不支持 HTTP/SSE 传输（计划在未来支持）
• 单个 Front 账户——每个服务实例只能使用一个账户
• 不支持 Webhook——仅支持出站 API 调用，不处理入站事件
• 不缓存——每个请求都会调用 Front API（依赖 Front 提供最新数据）
• 附件——v1 不支持文件上传/下载
• 应用渠道——不支持特定渠道的消息同步端点

开发

git clone https://github.com/wearehoust/front-mcp.git
cd front-mcp
npm install
npm test          # 519 tests
npm run lint      # ESLint strict
npm run type-check # TypeScript strict
npm run build     # Compile to dist/

测试

npm test              # Unit + integration tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run smoke         # Smoke test (builds, starts, verifies 26 tools)

项目包含 519 个单元/集成测试，以及一个包含 172 项操作的实时 API 测试脚本（scripts/live-test-full.js）。

发布流程

1. 使用 npm version X.Y.Z --no-git-tag-version 更新 package.json 和 package-lock.json。同时更新 server.json 中的两个版本字段、src/server.ts 中的服务版本，以及 CHANGELOG.md。
2. 确认已为 wearehoust/front-mcp 和 release.yml 工作流配置 npm 可信发布。发布工作流使用 GitHub OIDC 发布到 npm 和 MCP Registry。
3. 运行 npm ci、lint、类型检查、测试、构建和冒烟测试。检查打包后的 npm 制品及其 MCP 握手版本。
4. 以 chore: release vX.Y.Z 为提交说明创建提交，发起 PR，并在 CI 和审查通过后合并。
5. 获取 main 并在已验证的发布提交上创建带注释的 vX.Y.Z 标签。仅推送该标签：git push origin refs/tags/vX.Y.Z。
6. GitHub Actions 验证版本元数据、运行检查、发布 npm 包，然后在单独的任务中将 server.json 发布到 MCP Registry。如果 Registry 尚未识别到新的 npm 版本，注册流程会短暂重试。
7. 确认两个注册表都显示新版本，并对已发布的 npm 包进行冒烟测试。

如果 npm 发布成功，但注册表注册失败，请使用 Re-run failed jobs，仅重试注册表任务。若需恢复较早版本（包括使用单个发布任务的工作流），请在 main 分支打开 Actions → Release → Run workflow，并输入现有标签，例如 v1.1.1。此手动操作只会注册带标签的 server.json，不会重新发布 npm，也不会更改标签。恢复工作流必须先合并到 main。

安全

漏洞报告请参阅 SECURITY.md。

贡献

有关设置、代码规范和 PR 流程，请参阅 CONTRIBUTING.md。

许可证

MIT