内容
# Freshservice MCP 服务器
[](https://github.com/Node804/node804-freshservice-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/node804-freshservice-mcp/)
[](https://pypi.org/project/node804-freshservice-mcp/)
[](LICENSE)
一款适用于 Freshservice REST API 的可配置 MCP 服务器，具有基于权限的工具门控。
Freshservice 仅为每个账户提供一个 API 密钥，没有范围限制。此服务器通过引入 `FRESHSERVICE_MODE` 环境变量来解决这个问题，该变量控制哪些工具被暴露。被阻止的工具在注册时被排除，因此 LLM 永远不会看到它们。
## 权限模式
| 模式 | 工具 | 描述 |
|------|-------|-------------|
| `read` | 54 | 列出、查看、筛选、搜索所有模块。文件搜索。无修改。 |
| `standard` | 81 | 读取 + 创建/更新工单、变更、审批、服务请求、附件、时间记录。无删除，无代理/分组管理。 |
| `full` | 97 | 标准 + 产品、请求者、解决方案文章、删除备注/任务/时间记录。无代理创建，无工单/变更删除。 |
| `admin` | 107 | 所有功能。创建/删除代理、分组、工单、变更、附件。 |
默认模式为 `read`。
## 设置
### 先决条件
- **[uv](https://docs.astral.sh/uv/)** （推荐）- 为您管理 Python 和依赖项，具有哈希验证的安装
- 或 **Python 3.11+** 与 pip
- 一个具有 API 访问功能的 **Freshservice 账户**
### 获取 Freshservice API 密钥
1. 以代理身份登录您的 Freshservice 门户
2. 点击右上角的 **个人资料图片**
3. 进入 **个人资料设置**
4. 在右侧边栏的 **您的 API 密钥** 下显示您的 API 密钥
5. 复制它 - 您需要在下面的配置中使用它
> **注意：** Freshservice 为每个代理提供一个 API 密钥，没有范围限制。这就是为什么服务器有权限模式 - 这样您可以在 API 密钥本身具有完全访问权限的情况下限制 LLM 可以执行的操作。
### 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `FRESHSERVICE_DOMAIN` | 是 | 您的 Freshservice 域名（例如 `yourcompany.freshservice.com`） |
| `FRESHSERVICE_APIKEY` | 是 | 您的 Freshservice API 密钥 |
| `FRESHSERVICE_MODE` | 否 | 权限模式：`read`、`standard`、`full` 或 `admin`。默认：`read` |
| `FRESHSERVICE_CACHE_TTL` | 否 | 架构/参考数据的缓存生命周期（秒）。默认：`3600`（1 小时）。设置为 `0` 以禁用缓存。 |
| `FRESHSERVICE_FILE_SEARCH_PATHS` | 否 | 以分号分隔的目录列表，`find_file` 工具可以搜索（例如 `C:\Users\me\Docs;C:\Exports`）。文件发现所需。 |
| `FRESHSERVICE_AUDIT_LOG` | 否 | JSON-lines 审计日志的路径（例如 `C:\logs\freshservice-audit.jsonl`）。每个工具调用都会记录带有净化参数、成功/错误状态和计时信息。未设置时禁用。 |
### 安装
**选项 A - uv（推荐）。** 无需安装步骤：`uvx` 在首次运行时从 PyPI 获取包并缓存它。固定版本以确保升级是故意的：
```bash
uvx node804-freshservice-mcp==1.3.0
```
**选项 B - pip：**
```bash
pip install node804-freshservice-mcp
```
**选项 C - 从源代码（开发）：**
```bash
git clone <此仓库>
cd node804-freshservice-mcp
uv sync # 或：pip install -e ".[dev]"
```
每个选项都提供 `node804-freshservice-mcp` 命令和 `node804_freshservice_mcp` Python 模块。
### Claude 桌面
1. 打开您的 Claude 桌面配置文件：
- **Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac：** `~/Library/Application Support/Claude/claude_desktop_config.json`
2. 在 `mcpServers` 下添加 `node804-freshservice-mcp` 条目（如果文件不存在，请创建它）：
```json
{
"mcpServers": {
"FreshService": {
"command": "uvx",
"args": ["node804-freshservice-mcp==1.3.0"],
"env": {
"FRESHSERVICE_APIKEY": "您的 API 密钥",
"FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
"FRESHSERVICE_MODE": "standard",
"FRESHSERVICE_CACHE_TTL": 3600
}
}
}
}
```
如果您使用 pip 安装而不是 uv，请使用 `"command": "python"` 和 `"args": ["-m", "node804_freshservice_mcp.server"]`。
3. 重启 Claude 桌面 - 服务器在 Claude 需要它时自动启动。
**使用 `.env` 文件代替内联环境值：**
如果您不想将凭证保留在 `claude_desktop_config.json` 中，请创建一个 `.env` 文件在仓库根目录（参见 `.env.example`）并使用 `cwd` 指向服务器：
```bash
cp .env.example .env # 编辑您的凭证
```
```json
{
"mcpServers": {
"node804-freshservice-mcp": {
"command": "uvx",
"args": ["node804-freshservice-mcp==1.3.0"],
"cwd": "/path/to/node804-freshservice-mcp"
}
}
}
```
服务器在启动时调用 `load_dotenv()`，它从工作目录读取 `.env` 文件。`cwd` 字段告诉 Claude 桌面在仓库根目录启动服务器，文件位于那里。
### Claude 代码（CLI）
```bash
claude mcp add node804-freshservice-mcp \
-e FRESHSERVICE_APIKEY=您的 API 密钥 \
-e FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
-e FRESHSERVICE_MODE=standard \
-- uvx node804-freshservice-mcp==1.3.0
```
验证是否添加成功：
```bash
claude mcp list
```
### 验证它是否有效
连接后，询问您的 LLM：
- **“我的访问级别是什么？”** → 调用 `server_status`，显示模式、工具数量和速率限制信息
- **“我在 Freshservice 中是谁？”** → 调用 `get_current_agent`，确认 API 密钥有效并返回您的代理配置文件
如果任一失败，请查看下面的 [故障排除](#故障排除) 部分。
## 项目结构
```
src/node804_freshservice_mcp/
__init__.py # 包标记 + 版本
server.py # FastMCP 实例，条件工具装饰器，main()
config.py # 权限模式，工具层次结构，模式摘要
client.py # 共享 httpx 客户端，速率限制传输，响应缓存，身份验证
models.py # 枚举（TicketSource，ChangeStatus，...）+ Pydantic 模型
tools/
__init__.py # 导入所有工具模块以触发注册
tickets.py # 24 个工具 - 工单，会话，附件，时间记录
changes.py # 33 个工具 - 变更，审批，备注，任务，时间记录
service_catalog.py # 3 个工具 - 服务项目 + 请求
products.py # 4 个工具 - 产品 CRUD
requesters.py # 6 个工具 - 请求者 CRUD + 字段
agents.py # 7 个工具 - 当前代理，代理 CRUD + 字段
groups.py # 10 个工具 - 代理组 + 请求者组
canned_responses.py # 4 个工具 - canned 响应 + 文件夹
workspaces.py # 2 个工具 - 工作区列表
solutions.py # 13 个工具 - 知识库类别，文件夹，文章
files.py # 1 个工具 - 用于附件发现的本地文件搜索
```
## 模式详情
### read（默认）
对于需要查找工单信息、检查变更状态或搜索知识库的任何人都是安全的。不能修改任何内容。
包括：工单、变更、代理、请求者、分组、产品、服务目录、canned 响应、工作区和解决方案文章的获取/列表/筛选/查看操作。
### standard
日常 IT 工作。创建和更新工单，管理变更生命周期，发送回复，添加备注，处理审批。不能删除任何内容或管理代理/分组。
包括 `read` 中的所有内容以及：创建/更新工单，创建/更新变更，关闭变更，工单回复和备注，附件，变更任务/备注/时间记录，审批管理，服务请求。
### full
添加内容管理和请求者管理。对于需要管理知识库和请求者记录的高级人员。
包括 `standard` 中的所有内容以及：创建/更新产品，创建/更新请求者，解决方案文章/文件夹/类别管理，删除变更备注/任务/时间记录，请求者组 membership。
### admin
完全访问所有功能，包括破坏性操作。只有在您确实需要创建代理、删除工单或变更或管理组结构时才使用此功能。
包括 `full` 中的所有内容以及：删除工单，删除变更，创建/更新代理，创建/更新代理组，创建/更新请求者组。
## 附件
服务器提供用于在工单上上传、列出和删除文件的附件工具。
### 查找文件
使用 `find_file` 在本地文件系统按部分名称或通配符模式搜索文件，然后再附加它们。这是推荐在用户询问查找、定位或附加系统中的文件时要做的第一步 - 例如，询问“附加 Q4 报告”将找到 `Q4_Report.pdf` 在任何配置的搜索目录中。
搜索仅限于 `FRESHSERVICE_FILE_SEARCH_PATHS` 环境变量中列出的目录（以分号分隔）。匹配不区分大小写，支持部分名称（`report`）、通配符模式（`*.pdf`）和递归子目录搜索。
### 上传
使用 `add_ticket_attachment`、`add_note_attachment` 和 `add_reply_attachment` 上传文件。这些工具获取 MCP 服务器本地文件系统上的绝对文件路径，读取文件，检测 MIME 类型并通过 multipart form-data 上传。
> **注意：**MCP 服务器必须具有对要附加的文件的文件系统访问权限。这些工具旨在适用于 MCP 客户端（例如 Claude Code）在同一台机器上运行或可以将文件写入服务器可以读取的路径的场景。
### 列出和删除
- `list_ticket_attachments` - 列出工单上的所有附件（读取模式）
- `delete_ticket_attachment` / `delete_conversation_attachment` - 删除附件（admin 模式）
> **Freshservice 限制：** 单个工单上所有附件的总大小不能超过 40 MB。
## 代理签名
`send_ticket_reply` 和 `add_reply_attachment` 工具会自动在每个出站回复的末尾附加当前代理的 HTML 签名。签名从您的 Freshservice 代理配置文件中提取（与 Freshservice 门户中的 **配置文件 → 签名** 下的配置文件相同）。
- 签名数据来自缓存的 `get_current_agent` 调用，因此 **没有额外的 API 成本**。
- 如果配置文件中未配置签名，则会发送不带签名的回复。
- 内部备注（`create_ticket_note`、`add_note_attachment`）**不受影响** - 签名仅追加到对请求者可见的回复中。
## 提示示例
连接后，您可以询问类似的问题：
| 提示 | 会发生什么 | API 调用 |
|--------|-------------|-----------|
| "显示我的打开的工单" | `get_my_tickets` - 查找您的代理 ID，发现所有非已解决的状态，并在一次操作中过滤 | 1（暖缓存） |
| "工单 #4521 是关于什么的？” | `get_ticket_by_id` | 1 |
| "为 3 楼的打印机创建一个工单" | `create_ticket`，带有主题/描述/优先级 | 1 |
| "在工单 #4521 上添加备注，说明我们已订购零件" | `create_ticket_note` | 1 |
| "回复工单 #4521，让他们知道它已修复" | `send_ticket_reply` - 自动附加您的代理签名 | 1 |
| "查找 Q4 报告" | `find_file` - 在配置的目录中搜索匹配的文件 | 0 |
| "将此截图附加到工单 #4521" | `add_ticket_attachment` 带有文件路径 | 1 |
| "显示所有待审批的变更" | `filter_changes` 带有查询 `status:3` | 1 |
| "我们有哪些工单状态？” | `get_ticket_statuses` - 返回每个状态分类为已解决/未解决 | 0（缓存） |
| "我在 Freshservice 中是谁？” | `get_current_agent` - 返回您的代理配置文件 | 0（缓存） |
| "我的访问级别是什么？” | `server_status` - 显示模式、工具数量、速率限制 | 0 |
| "管理员添加了新的状态，请刷新缓存" | `clear_cache` - 丢弃所有缓存的数据 | 0 |
## API 效率
Freshservice 对每个租户每小时强制执行 API 速率限制。该服务器旨在保持在限制之内：
- **1 个工具调用 = 1 个 API 调用**，对于大多数工具。服务器不会进行后台调用、轮询或预获取操作。每个 API 调用仅在 LLM 显式调用工具时触发。附件上传使用 multipart form-data，每个上传算作一个 API 调用。
- **复合便利工具：`get_my_tickets` 将代理查找 + 状态发现 + 过滤器合并为一个工具调用（1 个 API 调用在暖缓存上，最多 3 个首次使用）。`get_ticket_statuses` 解析缓存的字段数据，零 API 成本。
- **速率限制处理：** 自定义传输读取每个响应上的 `X-RateLimit-Remaining`，并在 HTTP 429 时自动重试并延迟 `Retry-After`（最多 3 次重试）。
- **响应缓存：** 架构和参考数据工具在 `FRESHSERVICE_CACHE_TTL` 设置的持续时间内缓存成功的响应（默认为 1 小时）。这些是管理员配置的结构，实际上永远不会在会话中间更改。重复查找的成本为零 API 调用。使用 `clear_cache` 工具强制刷新。
## 始终可用的工具
`server_status` 和 `clear_cache` 工具无论模式如何都始终可用。
- **`server_status`** - 报告当前模式、工具数量、功能、缓存 TTL 和 API 速率限制剩余。
- **`clear_cache`** - 丢弃所有缓存的响应，以便下一个调用从 API 获取新鲜数据。
## 安全说明
- API 密钥仅通过 Basic auth 您的 Freshservice 域名发送 HTTPS
- 无遥测、无外部调用、无凭证日志记录
- 凭证在启动时验证；服务器如果缺少 `FRESHSERVICE_DOMAIN` 或 `FRESHSERVICE_APIKEY` 环境变量，则快速失败
- 模式限制在工具注册时强制执行。阻止的工具在 MCP 服务器的工具列表中不存在，因此 LLM 无法调用它们。
## 故障排除
| 症状 | 原因 | 修复 |
|---------|-------|-----|
| `RuntimeError: FRESHSERVICE_DOMAIN 环境变量是必需的` | 缺失或空 `FRESHSERVICE_DOMAIN` | 确保 MCP 配置中的 `env` 块具有正确的变量名和值 |
| `RuntimeError: FRESHSERVICE_APIKEY 环境变量是必需的` | 缺失或空 `FRESHSERVICE_APIKEY` | 与上述相同 - 检查 `env` 块，或如果从源代码运行，请检查 `.env` 文件 |
| 服务器启动但工具返回 `401 Unauthorized` | 无效 API 密钥 | 在 Freshservice 配置文件中重新生成密钥并更新您的配置 |
| 服务器启动但工具返回 `404 Not Found` | 域名格式错误 | 使用完整的域名（`yourcompany.freshservice.com`），而只是子域名 |
| 预期工具缺失 | 模式过于限制性 | 检查 `server_status` 查看当前模式，然后将 `FRESHSERVICE_MODE` 设置为更高级别 |
| `No module named node804_freshservice_mcp` | 包未安装 | 使用 `uvx` 配置（自动安装），或运行 `pip install node804-freshservice-mcp` |
| 旧数据管理员更改后 | 缓存响应 | 询问 LLM 调用 `clear_cache` 或将 `FRESHSERVICE_CACHE_TTL=0` 禁用缓存 |
## 开发
```bash
uv sync # 创建 .venv 从 pyproject.toml + uv.lock
uv run pytest tests/
或使用 pip：`pip install -e ".[dev]"` 然后 `pytest tests/`
`uv.lock` 固定了带有哈希的完整依赖图，以便重现安装。在更改 `pyproject.toml` 中的依赖项后，请运行 `uv lock` 并提交更新的锁文件。
## 遗产与变化
最初来自 [effytech/freshservice_mcp](https://github.com/effytech/freshservice_mcp)，它提供了一个单一文件证明概念，将 Freshservice 端点连接到 MCP。 大约 15-20% 的原始代码幸存下来 - 主要是基本的 API 调用模式和端点 URL。
除了基本 API 调用模式和端点 URL 之外，其他所有内容都已从头开始重写或添加：
| 区域 | 原始 | 现在 |
|------|----------|-----|
| **结构** | 单个文件，平坦 | 模块化包 - 10 个工具模块，共享客户端，配置，模型 |
| **安全性** | 暴露所有工具，单个无范围密钥 | 4 种权限模式；阻止的工具在注册时被排除 |
| **速率限制** | 无 | 429 自动重试与 `Retry-After`，速率限制跟踪通过 `server_status` |
| **缓存** | 无 | 可配置 TTL 的架构/参考数据缓存，`clear_cache` 工具 |
| **分页** | ~14 个工具仅返回第 1 页 | 所有列表工具公开 `page`/`per_page`；自动分页器上限为 3 页 |
| **便利工具** | 无 | `get_my_tickets`，`get_ticket_statuses`，`get_current_agent` |
| **工具描述** | 通用的一行描述 | 枚举值，查询语法示例，交叉引用，行为上下文 |
| **凭证处理** | 无 | 启动时验证，失败时快速失败，缺少环境变量 |
| **测试** | 无 | 55 个测试覆盖缓存、速率限制、配置、权限映射一致性、便利工具和附件 |
| **工具数量** | ~50 | 107 个权限控制 + 2 个始终开启 |
## 人工智能辅助开发
本项目中的部分代码，包括代码、测试和文档，都使用生成式 AI（Anthropic 的 Claude，Chat GPT）开发。所有更改都是人类审查后才合并并由自动化测试套件执行，但与任何软件一样，请在使用写访问权限（`standard` 模式或以上）信任它之前，请在非生产 Freshservice 实例上查看代码并进行测试。
## 许可
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器