内容
# Freshservice MCP 服务器
一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，连接 Claude、Codex 和其他 MCP 客户端到您的 Freshservice ITSM 实例。
## 支持的模块
| 模块 | 操作 |
|--------|-----------|
| **工单** | 创建、查看、列出、更新、删除、筛选、获取字段定义 |
| **对话** | 列出、回复工单、添加备注（公开/私密）、删除备注 |
| **变更** | 创建、查看、列出、更新、关闭、删除、筛选、任务、备注 |
| **资产** | 创建、查看、列出、更新、删除、搜索、筛选、获取类型 |
| **问题** | 创建、查看、列出 |
| **代理** | 列出、查看、筛选 |
| **请求者** | 创建、列出、查看、筛选 |
| **代理组** | 列出、查看 |
| **请求者组** | 列出、查看 |
| **产品** | 列出、查看 |
| **工作区** | 列出 |
| ** canned responses** | 列出文件夹、列出响应、查看 |
| **解决方案类别** | 创建、列出、查看 |
| **解决方案文件夹** | 创建、列出、查看 |
| **解决方案文章** | 创建、列出、查看、搜索 |
| **部门** | 列出、查看 |
| **位置** | 列出 |
| **软件** | 列出、查看 |
| **供应商** | 列出 |
| **服务目录** | 列出项目、查看项目 |
| **公告** | 列出 |
| **合同** | 列出、查看 |
| **采购订单** | 列出 |
## 前置条件
- **Python 3.10+**
- **uv** — 快速的 Python 包管理器
- **Claude Desktop**、**Claude Code** 或 **Codex 应用/CLI/IDE**（参见下面的[设置](#设置)）
- 具有 API 密钥的 **Freshservice 账户**
### 安装 uv
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 或使用 Homebrew
brew install uv
```
### 获取 Freshservice API 密钥
1. 登录到您的 Freshservice 门户
2. 点击您的**个人资料图片** → **个人资料设置**
3. 您的 API 密钥显示在右侧的**更改密码**下
## 设置
### 1. 克隆仓库
```bash
git clone https://github.com/matthewlboyd/freshservice-mcp.git
cd freshservice-mcp
```
### 2a. 配置 Claude Desktop
**选项 A — macOS 安装脚本（推荐）：**
```bash
./install.sh
```
该脚本自动处理所有操作：提示您输入仓库路径、API 密钥和域名，写入配置文件，测试连接，并重启 Claude Desktop。
**选项 B — 手动设置（所有平台）：**
打开 Claude Desktop 配置文件，使用任意文本编辑器：
| 操作系统 | 路径 |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
将以下内容粘贴到文件中，替换占位符值。如果文件尚不存在，请仅使用此内容创建它：
```json
{
"mcpServers": {
"freshservice": {
"command": "uv",
"args": [
"run",
"--directory",
"/full/path/to/freshservice-mcp",
"freshservice-mcp"
],
"env": {
"FRESHSERVICE_APIKEY": "your_api_key_here",
"FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com"
}
}
}
}
```
`FRESHSERVICE_DOMAIN` 应该只是主机名 — 不带 `https://` 前缀。
如果您位于具有 SSL 检测的企业代理后面，请在 `env` 块中添加 `SSL_CERT_FILE`，指向您的 CA 捆绑包：
```json
"env": {
"FRESHSERVICE_APIKEY": "your_api_key_here",
"FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
"SSL_CERT_FILE": "/path/to/your/ca-bundle.crt"
}
```
> 已经有其他 MCP 服务器？只需在现有的 `"mcpServers"` 对象中添加 `"freshservice": { ... }` 块即可。
**重启 Claude Desktop** — 退出并重新打开它。第一次启动将自动安装依赖项（大约需要 30 秒）。您应该在聊天输入中看到锤子图标（），表示 MCP 工具可用。
### 2b. 配置 Claude Code
**推荐：项目本地范围**
```bash
claude mcp add freshservice \
--scope local \
--env FRESHSERVICE_APIKEY=your_api_key_here \
--env FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
-- uv run --directory /full/path/to/freshservice-mcp freshservice-mcp
```
`--scope local` 将配置存储在 `.claude/settings.local.json` 中，**默认情况下 gitignore** — 您的 API 密钥不会被提交到版本控制中。
**替代：用户范围（在所有项目中均可访问）**
```bash
claude mcp add freshservice \
--scope user \
--env FRESHSERVICE_APIKEY=your_api_key_here \
--env FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
-- uv run --directory /full/path/to/freshservice-mcp freshservice-mcp
```
> **安全注意：** 永远不要在命令中硬编码凭证，使用 `--scope project` — `project` 范围写入 `.mcp.json`，通常会提交到版本控制中。使用 `local` 或 `user` 范围，或通过 shell 中已设置的环境变量传递凭证。
如果您位于具有 SSL 检测的企业代理后面，请在上面的命令中添加 `--env SSL_CERT_FILE=/path/to/your/ca-bundle.crt`。
**验证服务器已注册：**
```bash
claude mcp list
```
您应该在输出中看到 `freshservice`。无需重启 — Claude Code 在每个会话开始时都会获取 MCP 服务器。
### 2c. 配置 Codex 应用、CLI 或 IDE
Codex 应用、Codex CLI 和 Codex IDE 扩展通过 `config.toml` 共享 MCP 配置。服务器使用 Codex 支持的 stdio 传输，可以通过 Codex 特有的入口点别名 `freshservice-mcp-codex` 运行。
**选项 A — 安装脚本：**
```bash
./install-codex.sh
```
该脚本提示输入仓库路径、Freshservice API 密钥、域名和可选的 CA 捆绑包，然后将 `[mcp_servers.freshservice]` 块写入 `~/.codex/config.toml`（或 `$CODEX_HOME/config.toml` 如果设置了 `CODEX_HOME`）。
**选项 B — Codex CLI：**
```bash
codex mcp add freshservice \
--env FRESHSERVICE_APIKEY=your_api_key_here \
--env FRESHSERVICE_DOMAIN=yourcompany.freshservice.com \
-- uv run --directory /full/path/to/freshservice-mcp freshservice-mcp-codex
```
如果您位于具有 SSL 检测的企业代理后面，请添加 `--env SSL_CERT_FILE=/path/to/your/ca-bundle.crt`。
**选项 C — 手动 `config.toml`：**
打开 Codex **设置** → **集成与 MCP** → **打开 config.toml**，或直接编辑 `~/.codex/config.toml`。添加此块，替换占位符：
```toml
[mcp_servers.freshservice]
enabled = true
command = "uv"
args = [
"run",
"--directory",
"/full/path/to/freshservice-mcp",
"freshservice-mcp-codex",
]
startup_timeout_sec = 30
tool_timeout_sec = 120
[mcp_servers.freshservice.env]
FRESHSERVICE_APIKEY = "your_api_key_here"
FRESHSERVICE_DOMAIN = "yourcompany.freshservice.com"
```
`FRESHSERVICE_DOMAIN` 应该只是主机名 — 不带 `https://` 前缀。
如果您位于具有 SSL 检测的企业代理后面，请在 env 块中添加：
```toml
SSL_CERT_FILE = "/path/to/your/ca-bundle.crt"
```
> **安全注意：** `[mcp_servers.freshservice.env]` 下的值以纯文本形式存储在 `config.toml` 中。如果您已经通过其他方式为 Codex 进程提供这些变量，可以使用 `env_vars = ["FRESHSERVICE_APIKEY", "FRESHSERVICE_DOMAIN"]` 代替 env 表。
重启 Codex 应用，或启动新的 Codex CLI/IDE 会话。在 Codex 中，使用 `/mcp` 确认已加载 `freshservice` 服务器。
## 示例提示
### 工单
- "显示所有紧急的打开工单"
- "为 VPN 连接问题创建一个工单 — 指派给网络团队，优先级高"
- "更新工单 #4521 为已解决"
- "查找本周由 john@example.com 创建的所有工单"
### 变更
- "为周六的服务器维护创建变更请求，10pm–2am"
- "显示所有待批准的变更"
- "关闭变更 #89 — 迁移成功完成"
### 资产
- "列出资产清单中的所有笔记本电脑"
- "搜索标记为 'datacenter' 的资产"
- "显示所有未指派的硬件资产"
### 知识库
- "在知识库中搜索 VPN 设置说明"
- "创建一个新的解决方案文章，关于如何重置密码"
- "列出 onboarding 文件夹中的所有文章"
### 通用
- "Help Desk 组有多少个打开的工单？"
- "列出所有活动代理及其部门"
- "显示系统中注册的所有软件"
## 运行测试
测试套件涵盖所有 62 种工具和 API 客户端（共 117 个测试）。不需要 Freshservice 凭证 — 所有测试都使用模拟的 HTTP 调用。
**安装开发依赖项：**
```bash
uv pip install -e ".[dev]"
```
**运行所有测试：**
```bash
uv run pytest tests/ -v
```
**运行特定模块的测试：**
```bash
uv run pytest tests/test_tickets.py -v
```
**测试文件：**
| 文件 | 测试内容 |
|------|---------------|
| `test_client.py` | HTTP 客户端 — 认证、域名规范化、错误处理 |
| `test_tickets.py` | 工单工具 |
| `test_conversations.py` | 回复、备注、删除备注 |
| `test_changes.py` | 变更请求工具 |
| `test_assets.py` | 资产工具 |
| `test_people.py` | 代理、请求者、组 |
| `test_knowledge_base.py` | 解决方案类别、文件夹、文章 |
| `test_misc.py` | 问题、产品、工作区、canned responses、部门、位置、软件、供应商、服务目录、公告、合同、采购订单 |
## 故障排除
**Claude Desktop 中没有出现工具**
确保 `--directory` 中的路径是仓库的绝对路径，并且您已经完全退出并重启了 Claude（不仅仅是关闭窗口）。
**Claude Code 中没有出现工具**
运行 `claude mcp list` 以确认服务器已注册。如果已注册，请启动新的 `claude` 会话 — MCP 服务器在会话开始时加载。如果丢失，请重新运行 `claude mcp add` 命令。
**Codex 中没有出现工具**
检查 `~/.codex/config.toml`（或 `$CODEX_HOME/config.toml`）中是否有 `[mcp_servers.freshservice]` 块，然后重启 Codex 应用或启动新的 Codex CLI/IDE 会话。在 Codex 中，运行 `/mcp` 以检查已加载的 MCP 服务器。如果第一次启动超时，而 `uv` 安装依赖项，请保持 `startup_timeout_sec = 30` 或增加它。
**身份验证错误（401）**
您的 API 密钥不正确。请在 Freshservice → 个人资料设置中重新检查。复制时使用复制图标，而不是手动选择文本。
**403 禁止**
API 密钥对该操作无权限，或域名错误。请确认 `FRESHSERVICE_DOMAIN` 仅为域名（例如 `yourcompany.freshservice.com`），不带 `https://` 前缀。
**SSL 证书错误**
如果您位于具有 SSL 检测的企业代理后面，请求将因证书验证错误而失败。请将 `SSL_CERT_FILE` 环境变量设置为您的组织的 CA 捆绑包路径。在 Claude Desktop 中，将其添加到 `claude_desktop_config.json` 中的 `"env"` 块中。在 Claude Code 中，在运行 `claude mcp add` 时传递 `--env SSL_CERT_FILE=/path/to/ca-bundle.crt`。在 Codex 中，在 `[mcp_servers.freshservice.env]` 下添加 `SSL_CERT_FILE = "/path/to/your/ca-bundle.crt"`。
**速率限制（429）**
Freshservice 根据您的计划强制执行每分钟 API 速率限制。请等待片刻并重试。
**筛选查询返回错误**
筛选字符串必须使用双引号字段值。示例：`"status:2 AND priority:4"` 而不是 `status:2 AND priority:4`。
**检查日志**
如果某些操作无法正常工作，请检查 MCP 服务器日志：
- **macOS:** `~/Library/Logs/Claude/mcp-server-freshservice.log`
- **Windows:** `%APPDATA%\Claude\logs\mcp-server-freshservice.log`
## 许可证
MIT
