Freshservice MCP Server

Freshservice MCP 服务

概述

一个功能强大的 MCP（Model Context Protocol）服务实现，可与 Freshservice 无缝集成，让 AI 模型能够与 Freshservice 模块交互并执行各种 IT 服务管理操作。这个集成桥接使 AI 助手能够管理和解决 IT 服务工单，从而简化支持工作流。

主要功能

• 企业级 Freshservice 集成：与 Freshservice API 端点直接、安全地通信
• 兼容 AI 模型：支持 Claude 和其他 AI 模型通过 Freshservice 执行服务台操作
• 自动化 ITSM 管理：高效处理工单创建、更新、回复和资产管理
• 加速工作流：减少日常 IT 服务任务中的人工干预

支持的 Freshservice 模块

此 MCP 服务目前支持在多种 Freshservice 模块中执行操作：

• 工单
• 变更
• 对话
• 产品
• 请求者
• Agent
• Agent 组
• 请求者组
• 预设回复
• 预设回复文件夹
• 工作区
• 解决方案类别
• 解决方案文件夹
• 解决方案文章

组件与工具

该服务提供全面的 Freshservice 操作工具集：

工单管理

工具	描述	关键参数
create_ticket	创建新服务工单	subject、description、source、priority、status、email
update_ticket	更新现有工单	ticket_id、updates
delete_ticket	删除工单	ticket_id
filter_tickets	查找符合条件的工单	query
get_ticket_fields	获取工单字段定义	无
get_tickets	分页列出所有工单	page、per_page
get_ticket_by_id	获取单个工单的详细信息	ticket_id

变更管理

工具	描述	关键参数
get_changes	分页列出所有变更	page、per_page、query
filter_changes	使用高级查询筛选变更	query、page、per_page
get_change_by_id	获取单个变更的详细信息	change_id
create_change	创建新的变更请求	requester_id、subject、description、priority、impact、status、risk、change_type
update_change	更新现有变更	change_id、change_fields
close_change	关闭变更并说明结果	change_id、change_result_explanation
delete_change	删除变更	change_id
get_change_tasks	获取变更的任务	change_id
create_change_note	为变更添加备注	change_id、body

🚨 重要：筛选查询语法

使用 get_changes 或 filter_changes 的 query 参数时，查询字符串必须用双引号括起来，Freshservice API 才能正常工作：

✅ 正确："status:3"、"approval_status:1 AND status:<6"
❌ 错误：status:3（会导致 500 Internal Server Error）

常见查询示例：

• "status:3" - 等待审批的变更
• "approval_status:1" - 已批准的变更
• "approval_status:1 AND status:<6" - 已批准且尚未关闭的变更
• "planned_start_date:>'2025-07-14'" - 在指定日期之后开始的变更
• "status:3 AND priority:1" - 等待审批的高优先级变更

入门指南

通过 Smithery 安装

通过 Smithery 自动安装 freshservice_mcp：

npx -y @smithery/cli install @effytech/freshservice_mcp --client claude

前提条件

• Freshservice 帐户（在 freshservice.com 注册）
• Freshservice API 密钥
• 已安装 uvx（使用 pip install uv 或 brew install uv 安装）

配置

1. 从管理面板生成 Freshservice API 密钥：

   • 前往 Profile Settings → API Settings
   • 复制 API 密钥以供配置

2. 按照下方说明设置域名和身份验证信息

在 Claude Desktop 中使用

1. 从官方网站安装 Claude Desktop
2. 将以下配置添加到 claude_desktop_config.json：

"mcpServers": {
  "freshservice-mcp": {
    "command": "uvx",
    "args": [
        "freshservice-mcp"
    ],
    "env": {
      "FRESHSERVICE_APIKEY": "<YOUR_FRESHSERVICE_APIKEY>",
      "FRESHSERVICE_DOMAIN": "<YOUR_FRESHSERVICE_DOMAIN>"
    }
  }
}

重要提示：将 <YOUR_FRESHSERVICE_APIKEY> 替换为你的实际 API 密钥，并将 <YOUR_FRESHSERVICE_DOMAIN> 替换为你的域名（例如，yourcompany.freshservice.com）

操作示例

配置完成后，你可以让 Claude 执行以下操作：

工单：

• “创建一个新的事件工单，主题为‘营销部门网络连接问题’，描述为‘营销区域的用户无法连接 Wi-Fi’，并将优先级设为高”
• “列出过去 24 小时内报告的所有严重事件”
• “将工单 #12345 的状态更新为已解决”

变更：

• “创建一项变更请求，安排在下周二凌晨 2 点进行服务器维护”
• “将变更请求 #45678 的状态更新为‘已批准’”
• “关闭变更 #5092，结果说明为‘已成功部署到生产环境。所有测试均已通过。’”
• “列出所有待处理的变更”

其他操作：

• “显示资产标签为‘LT-2023-087’的笔记本电脑资产详情”
• “创建一篇有关密码重置流程的解决方案文章”

测试

如需测试，你可以手动启动服务：

uvx freshservice-mcp --env FRESHSERVICE_APIKEY=<your_api_key> --env FRESHSERVICE_DOMAIN=<your_domain>

故障排除

• 确认 Freshservice API 密钥和域名正确
• 确保与 Freshservice 服务器的网络连接正常
• 检查 API 速率限制和配额
• 确认 uvx 命令在你的 PATH 中可用

许可证

此 MCP 服务采用 MIT 许可证。完整详情请参阅项目仓库中的 LICENSE 文件。

更多资源

• Freshservice API 文档
• Claude Desktop 集成指南
• MCP 协议规范

---

由 effy 倾心打造 ❤️