Front MCP

io.github.wearehoust由 GitHub 账号 wearehoust 发布v1.0.1更新于 Oct 24, 2026

MCP server for Front: conversations, contacts, messages, tags, and inbox workflows.

已验证STDIO仅桌面效率与工作流沟通与协作商业与电商

概览

AI 生成的概览

让助手通过 26 个工具、172 个操作处理 Front 的客户会话、联系人、消息、标签和收件箱工作流。

可以做什么
把 MCP 客户端连接到 Front API，使助手可以搜索和读取会话、查看消息、列出和管理联系人、标签、收件箱、团队成员和知识库，并创建草稿或发送回复。操作按工具分组，例如 conversations、contacts、messages、tags、drafts 和 analytics。策略引擎把每个操作分为读取、写入或破坏性三类：写入操作需要两步确认，破坏性操作默认被拒绝。
适用场景
适合已经使用 Front 共享收件箱和客服流程的团队，希望助手在不离开聊天客户端的情况下查找会话、总结会话串、管理联系人和标签，或起草回复。它面向客服与运营工作流，而不是通用的网页或文件任务。
运行要求
通过 npm 包 @houst-com/front-mcp 以 stdio 在本地运行，需要 Node.js 和 npx。需要 Front 账号，可用 FRONT_API_TOKEN 中的 API 令牌认证，或用 FRONT_MCP_AUTH_METHOD 与 FRONT_MCP_OAUTH_SECRET 走 OAuth，并在 Front 中配置 OAuth 应用和重定向 URI。Front 权限（Read、Write、Delete、Send）必须与所用操作匹配。仅支持桌面端，无 HTTP 或 SSE 传输。
安装前请注意
该服务器持有可访问真实客户会话的凭据：FRONT_API_TOKEN 或 FRONT_MCP_OAUTH_SECRET，令牌在本地加密存储。写入操作会创建、更新、分配或发送消息，需要确认；删除、移除等破坏性操作默认被拒绝，但可通过自定义策略文件放行。发送回复和导入消息会作用于真实的 Front 数据，会话内容会传给模型提供方。此版本不支持附件。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Front MCP，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

Front MCP

[CI] [npm] [License: MIT] [Node] [TypeScript] [MCP] [Front API]

Use Front from MCP clients that support local stdio servers. Search conversations, manage contacts, send messages, tag, assign, and automate inbox workflows — 26 tools, 172 actions.

Quick Start

  1. Get a Front API token from Settings > Developers > API tokens.

  2. Add this server to the top-level mcpServers object in your Claude Code user configuration (~/.claude.json), preserving any existing settings and servers. For a shared project configuration, use .mcp.json instead. See Claude Code's MCP configuration guide.

json
{  "mcpServers": {    "front": {      "command": "npx",      "args": ["-y", "@houst-com/front-mcp"],      "env": {        "FRONT_API_TOKEN": "your-front-api-token"      }    }  }}
  1. Start Claude Code. The Front tools are now available.

Node.js 20 or newer is required. The server runs locally using your own Front credentials; no Houst-hosted service is required. Keep API tokens out of version control; shared .mcp.json files should use "FRONT_API_TOKEN": "${FRONT_API_TOKEN}" and set that variable in the environment that launches Claude Code.

Example Workflows

Search for a conversation:

"Search Front conversations about billing issues"

Inspect a thread:

"Get the messages in conversation cnv_abc123"

Manage contacts:

"List contacts and find the one with email [email protected]"

Tag and assign:

"Tag conversation cnv_abc123 with 'urgent' and assign it to teammate tea_xyz"

Draft a reply:

"Create a draft reply to conversation cnv_abc123 saying we'll follow up tomorrow"

OAuth Setup (Recommended)

OAuth provides automatic token refresh and better security than API tokens.

  1. Create a Front app at Settings > Developers > OAuth apps.
  2. Set the redirect URI to https://localhost:9876/callback.
  3. Enable the resource permissions your MCP server needs (Read, Write, Delete, Send).
  4. Save the app — copy the Client ID from the OAuth feature (not the App secret from Settings).
  5. Create ~/.front-mcp/config.json:
json
{  "auth": {    "method": "oauth",    "oauth": {      "client_id": "your-client-id",      "client_secret_env": "FRONT_MCP_OAUTH_SECRET",      "redirect_port": 9876,      "scopes": []    }  }}
  1. Configure Claude Code:
json
{  "mcpServers": {    "front": {      "command": "npx",      "args": ["-y", "@houst-com/front-mcp"],      "env": {        "FRONT_MCP_AUTH_METHOD": "oauth",        "FRONT_MCP_OAUTH_SECRET": "your-oauth-client-secret"      }    }  }}
  1. Run npx @houst-com/front-mcp auth to authenticate (opens browser).
  2. Tokens are encrypted and stored locally (AES-256-GCM, 0600 permissions).

Auth CLI

bash
front-mcp auth            # Start OAuth flowfront-mcp auth --status   # Check auth state (no token values shown)front-mcp auth --clear    # Remove stored tokensfront-mcp --version       # Show versionfront-mcp --help          # Show usage

Front Permissions

The MCP server needs Front API permissions matching the actions you want to use:

PermissionRequired for
ReadAll list/get/search actions
Writecreate, update, assign, add, merge, reply
Deletedelete, remove actions
Sendmessages.create, messages.reply

For OAuth, configure these in your Front app under Features > OAuth > Resource permissions. For API tokens, permissions are set when creating the token.

Tools Reference

ToolActions
accountslist, get, create, update, delete, list_contacts, add_contact, remove_contact
analyticscreate_export, get_export, create_report, get_report
channelslist, get, update, validate, create, list_for_teammate, list_for_team
commentslist, get, create, update, list_mentions, reply
contact_groupslist, create, delete, list_contacts, add_contacts, remove_contacts
contact_listslist, create, delete, list_contacts, add_contacts, remove_contacts
contact_noteslist, create
contactslist, get, create, update, delete, merge, list_conversations, add_handle, remove_handle
conversationslist, 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_fieldslist_for_accounts, list_for_contacts, list_for_conversations, list_for_inboxes, list_for_links, list_for_teammates
draftslist, create, create_reply, update, delete
eventslist, get
inboxeslist, get, create, list_channels, list_conversations, list_access, grant_access, revoke_access
knowledge_baseslist, get, create, update, list_categories, list_articles, get_article, create_article, update_article, delete_article, get_category, create_category, update_category, delete_category
linkslist, get, create, update, list_conversations
message_template_folderslist, get, create, update, delete, list_children, create_child
message_templateslist, get, create, update, delete
messagesget, create, reply, import, receive_custom, get_seen_status, mark_seen
ruleslist, get, list_for_teammate, list_for_team
shiftslist, get, create, update, list_teammates, add_teammates, remove_teammates
signatureslist, get, update, delete, create_for_teammate, create_for_team
tagslist, get, create, update, delete, list_children, create_child, list_conversations
teammate_groupslist, get, create, update, delete, list_inboxes, add_inboxes, remove_inboxes, list_teammates, add_teammates, remove_teammates, list_teams, add_teams, remove_teams
teammateslist, get, update, list_conversations, list_inboxes
teamslist, get, add_teammates, remove_teammates
token_identityget

See docs/TOOL_REFERENCE.md for the complete reference with policy tiers per action.

Policy Engine

Every action is classified into a tier with a default decision:

TierDefaultExamples
readallowlist, get, search
writeconfirmcreate, update, assign
destructivedenydelete, remove

Write actions require a two-step confirmation: the first call returns a prompt, the second call with confirm: true executes. Destructive actions are denied by default.

Custom Policy

Create ~/.front-mcp/policy.json:

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

Override precedence: specific action > tool wildcard > tier default.

Security Model

  • HTTPS enforced — no HTTP fallback, ever
  • Token encryption — AES-256-GCM with PBKDF2 key derivation
  • File permissions — token file is 0600 (owner read/write only)
  • Output sanitization — configurable field redaction before LLM sees data
  • Log redaction — sensitive fields redacted from all log output
  • Policy engine — destructive actions denied by default, write actions require confirmation
  • No secrets in stdout — stdout is reserved for MCP protocol only
  • Minimal dependencies — native fetch, Node.js crypto, pinned exact versions

Environment Variables

VariableRequiredDescription
FRONT_API_TOKENYes (unless OAuth)Front API token
FRONT_MCP_AUTH_METHODNooauth or api_token (default: api_token)
FRONT_MCP_OAUTH_SECRETYes (if OAuth)OAuth client secret
FRONT_MCP_LOG_LEVELNoerror, warn, info, debug (default: info)
FRONT_MCP_POLICY_FILENoPath to custom policy JSON file

Limitations

  • stdio transport only — no HTTP/SSE transport in v1 (planned for future)
  • Single Front account — one account per server instance
  • No webhook support — outbound API calls only, no inbound event processing
  • No caching — every request hits the Front API (relies on Front's freshness)
  • Attachments — file upload/download not supported in v1
  • Application channels — channel-specific message sync endpoints not supported

Development

bash
git clone https://github.com/wearehoust/front-mcp.gitcd front-mcpnpm installnpm test          # 519 testsnpm run lint      # ESLint strictnpm run type-check # TypeScript strictnpm run build     # Compile to dist/

Testing

bash
npm test              # Unit + integration testsnpm run test:watch    # Watch modenpm run test:coverage # Coverage reportnpm run smoke         # Smoke test (builds, starts, verifies 26 tools)

The project includes 519 unit/integration tests and a 172-action live API test script (scripts/live-test-full.js).

Release Process

  1. Update package.json and package-lock.json with npm version X.Y.Z --no-git-tag-version. Update both version fields in server.json, the server version in src/server.ts, and CHANGELOG.md.
  2. Confirm npm trusted publishing is configured for wearehoust/front-mcp and the release.yml workflow. The release workflow uses GitHub OIDC for npm and the MCP Registry.
  3. Run npm ci, lint, type-check, tests, build, and smoke. Check the packed npm artifact and its MCP handshake version.
  4. Commit as chore: release vX.Y.Z, open a PR, and merge after CI and review pass.
  5. Fetch main and create an annotated vX.Y.Z tag on the verified release commit. Push only that tag with git push origin refs/tags/vX.Y.Z.
  6. GitHub Actions verifies version metadata, runs the checks, publishes the npm package, and then publishes server.json to the MCP Registry in a separate job. Registration retries briefly when the registry cannot yet see the new npm version.
  7. Verify both registries report the new version and smoke-test the published npm package.

If npm publication succeeds but registry registration fails, use Re-run failed jobs to retry only the registry job. For recovery of an older release (including workflows that used a single publish job), open Actions → Release → Run workflow on main and enter the existing tag, such as v1.1.1. This manual action only registers the tagged server.json; it never republishes npm or changes the tag. The recovery workflow must first be merged into main.

Security

See SECURITY.md for vulnerability reporting.

Contributing

See CONTRIBUTING.md for setup, code standards, and PR process.

License

MIT

来源：README.md，提交 0151928

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v1.0.1最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分