ITSM集成服务器

Freshservice MCP服务器

A. 模型上下文协议（MCP） 将Claude、Codex和其他MCP客户端连接到Freshservice ITSM实例的服务器。

支持的模块

先决条件

• Python 3.10+
• 紫外线 --快速Python包管理器
• 克劳德桌面, 克劳德代码，或 Codex应用程序/CLI/IDE （参见 设置 在......下面
• A. Freshservice帐户 带有API密钥

安装uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with Homebrew
brew install uv

获取您的Freshservice API密钥

1. 登录您的Freshservice门户
2. 点击您的 头像 → 个人资料设置
3. 您的API密钥显示在下面的右侧 更改密码

设置

1.克隆存储库

git clone https://github.com/matthewlboyd/freshservice-mcp.git
cd freshservice-mcp

2a。配置Claude桌面

选项A——macOS安装脚本（推荐）：

./install.sh

这会自动处理一切：提示您的回购路径、API密钥和域，编写配置，测试连接，并重新启动Claude Desktop。

选项B——手动设置（所有平台）：

在任何文本编辑器中打开Claude Desktop配置文件：

将以下内容粘贴到文件中，替换占位符值。如果文件还不存在，请仅使用以下内容创建它：

{
  "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检查的公司代理，请添加 SSL_CERT_FILE 到 env 指向CA包的块：

"env": {
  "FRESHSERVICE_APIKEY": "your_api_key_here",
  "FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
  "SSL_CERT_FILE": "/path/to/your/ca-bundle.crt"
}

已经有其他MCP服务器了吗？只添加 "freshservice": { ... } 阻塞现有的 "mcpServers" 对象，而不是替换整个文件。

重新启动克劳德桌面 --退出并重新打开它。第一次启动将自动安装依赖项（大约需要30秒）。你应该看到一个锤子图标(🔨) 在聊天输入中，指示MCP工具可用。

2b。配置Claude代码

推荐：项目局部范围

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，即 默认情况下被忽略 -您的API密钥将不会提交给版本控制。

备选方案：用户范围（在所有项目中都可用）

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 按照上面的命令。

验证服务器是否已注册：

claude mcp list

你应该看到 freshservice 在输出中。无需重新启动——Claude Code在每个会话开始时都会启动MCP服务器。

2c。配置Codex应用程序、CLI或IDE

Codex应用程序、Codex CLI和Codex IDE扩展通过以下方式共享MCP配置 config.toml。服务器使用Codex支持的stdio传输，可以通过Codex特定的入口点别名运行 freshservice-mcp-codex.

选项A--安装脚本：

./install-codex.sh

这会提示您输入repo路径、Freshservice API密钥、域和可选的CA捆绑包，然后编写 [mcp_servers.freshservice] 阻止到 ~/.codex/config.toml （或 $CODEX_HOME/config.toml 如果 CODEX_HOME 已设置）。

选项B——Codex CLI：

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/ca-bundle.crt.

选项C——手动 config.toml:

开放法典 设置 → 集成和MCP → 打开config.toml，或编辑 ~/.codex/config.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块中：

SSL_CERT_FILE = "/path/to/your/ca-bundle.crt"

安全说明： 以下数值 [mcp_servers.freshservice.env] 以明文形式存储在 config.toml。如果您已经以其他方式向食品法典委员会流程提供了这些变量，则可以使用 env_vars = ["FRESHSERVICE_APIKEY", "FRESHSERVICE_DOMAIN"] 而不是env表。

重新启动Codex应用程序，或启动新的Codex CLI/IDE会话。在Codex中，使用 /mcp 确认 freshservice 服务器已加载。

示例提示

门票

• “显示所有打开的紧急票”
• “为VPN连接问题创建工单——分配给网络团队，高优先级”
• “将票#4521更新为已解决”
• “查找本周创建的所有门票john@example.com"

变化

• “本周六晚上10点至凌晨2点创建服务器维护更改请求”
• “显示所有等待批准的更改”
• “关闭更改#89--迁移已成功完成”

资产

• “列出资产清单中的所有笔记本电脑”
• “搜索标记为‘数据中心’的资产”
• “显示所有未分配的硬件资产”

知识库

• “在知识库中搜索VPN设置说明”
• “创建一篇关于如何重置密码的新解决方案文章”
• “列出入职文件夹中的所有文章”

通用

• “帮助台组分配了多少张未结工单？”
• “列出所有活动代理及其部门”
• “显示系统中注册的所有软件”

运行测试

测试套件涵盖了所有62个工具和API客户端（总共117个测试）。不需要Freshservice凭据——所有测试都使用模拟的HTTP调用。

安装开发依赖项：

uv pip install -e ".[dev]"

运行所有测试：

uv run pytest tests/ -v

运行特定模块的测试：

uv run pytest tests/test_tickets.py -v

测试文件：

故障排除

工具未出现在Claude Desktop中 确保路径正确 --directory 是仓库的绝对路径，您已经完全退出并重新启动了Claude（而不仅仅是关闭窗口）。

工具未出现在Claude代码中 跑 claude mcp list 以确认服务器已注册。如果是，开始一个新的 claude session——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中，将其添加到 "env" 挡住 claude_desktop_config.json.在克劳德密码中，通过 --env SSL_CERT_FILE=/path/to/ca-bundle.crt 跑步时 claude mcp add.在Codex中，添加 SSL_CERT_FILE = "/path/to/ca-bundle.crt" 在...之下 [mcp_servers.freshservice.env].

速率限制（429） Freshservice根据您的计划强制执行API费率限制。请稍等，然后重试。

筛选器查询返回错误 筛选器字符串必须使用双引号字段值。例子： "status:2 AND priority:4" 不 status:2 AND priority:4.

检查日志 如果有什么不起作用，请检查MCP服务器日志：

• macOS： ~/Library/Logs/Claude/mcp-server-freshservice.log
• 窗户： %APPDATA%\Claude\logs\mcp-server-freshservice.log

许可证

麻省理工学院