Freshdesk

@mindstone/mcp-server-freshdesk

适用于 Model Context Protocol 主机的 Freshdesk 支持 MCP 服务。通过标准化的 MCP 接口管理服务台工单、搜索和筛选支持请求、回复客户、添加内部备注以及配置 Freshdesk 账户。

状态

• 版本： 0.3.1 · npm
• 身份验证： API 密钥（按账户配置，通过 FRESHDESK_CONFIG_PATH 存储在磁盘上）
• 工具： 20（账户、工单、联系人、公司、知识库、发现）
• 接口： cloud-api
• 机器可读： STATUS.json

要求

• Node.js 20+
• npm

一键安装

点击按钮后，主机将提示你填写：FRESHDESK_CONFIG_PATH。

{
  "mcpServers": {
    "Freshdesk": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-freshdesk"
      ],
      "env": {
        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
      }
    }
  }
}

快速开始

安装与构建

cd <path-to-repo>/connectors/freshdesk
npm install
npm run build

npx（发布后使用）

npx -y @mindstone/mcp-server-freshdesk

本地

node dist/index.js

配置

环境变量

• FRESHDESK_CONFIG_PATH — 存储账户凭据的配置目录路径（默认为 ~/.mcp/freshdesk）
• MCP_HOST_BRIDGE_STATE — 主机桥接状态文件的可选路径，用于凭据管理
• MINDSTONE_REBEL_BRIDGE_STATE — 与 MCP_HOST_BRIDGE_STATE 向后兼容的别名

主机配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "Freshdesk": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-freshdesk"],
      "env": {
        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
      }
    }
  }
}

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "Freshdesk": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/freshdesk/dist/index.js"],
      "env": {
        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
      }
    }
  }
}

工具（20）

账户管理

• configure_freshdesk — 使用子域名和 API 密钥连接 Freshdesk 账户
• list_freshdesk_accounts — 列出已连接的 Freshdesk 账户及其 Agent 电子邮件地址
• remove_freshdesk_account — 断开 Freshdesk 账户

工单

• list_freshdesk_tickets — 使用预定义筛选条件列出工单
• get_freshdesk_ticket — 按 ID 获取单个工单，可选择包含对话
• search_freshdesk_tickets — 使用 Freshdesk 查询语法搜索工单
• create_freshdesk_ticket — 创建新工单
• update_freshdesk_ticket — 更新工单字段、状态或受理人
• reply_to_freshdesk_ticket — 在工单中添加公开回复
• add_freshdesk_note — 在工单中添加私人或公开备注

发现

• list_freshdesk_ticket_fields — 列出所有工单字段，包括自定义字段
• list_freshdesk_agents — 列出 Agent（支持人员）；分配工单时使用其 ID 作为 responder_id
• list_freshdesk_groups — 列出组（Agent 团队）；分配工单时使用其 ID 作为 group_id

联系人与公司

• list_freshdesk_contacts — 列出联系人，可按精确邮箱或公司 ID 筛选
• search_freshdesk_contacts — 使用 Freshdesk 查询语法搜索联系人
• get_freshdesk_contact — 按 ID 获取单个联系人
• list_freshdesk_companies — 列出客户组织
• get_freshdesk_company — 按 ID 获取单个公司

知识库

• search_freshdesk_solutions — 按关键词搜索解决方案文章（分页：每页 30 篇，使用 page 参数，并提供 hasMore 指示）
• get_freshdesk_solution_article — 按 ID 获取完整的解决方案文章

安全

• Freshdesk API 返回的所有字符串（名称、正文、标签、邮箱、电话号码、公司域名、自定义字段键/值、工单字段元数据，等等）均会封装在 <untrusted-content source="…"> 信封中，以便宿主大模型将其视为数据而非指令。只有数字形式的连接器元数据（ID、状态、优先级）会以原始形式返回。
• 凭据存储在 FRESHDESK_CONFIG_PATH 下的 accounts.json 中，权限为 0600（配置目录权限为 0700）。
• 供应商错误正文、原始 Retry-After 标头文本以及包含查询参数的 URL 不会写入日志，也不会在工具错误中显示。
• 无效的 status/priority 值以及超出范围的 ID/分页输入会在发出任何请求前被拒绝。

许可证

FSL-1.1-MIT — Functional Source License，Version 1.1，未来采用 MIT 许可证。该软件将于 2030-04-08 转为 MIT 许可证。