OTRS MCP Server

Name: OTRS MCP Server
Author: spoonbobo

本地服务

github.com/spoonbobo商业与营销872 周前更新

代码仓库

关于 OTRS MCP Server

OTRS MCP Server 将 OTRS 工单与配置项功能接入 MCP，面向需要通过 AI 助手管理 OTRS 的团队。它提供可配置的工具，以及工单历史和 CMDB 资源访问。

主要功能

01创建、查询和更新工单
02查看工单详情与历史
03管理 CMDB 配置项
04会话创建与身份验证
05可配置开放给客户端的工具

适用场景

01通过 AI 助手创建或更新工单
02搜索工单并查看处理历史
03查找 OTRS 配置项信息

MCP 相关

作为 MCP 服务，它向 MCP 客户端提供 OTRS 工单、工单历史及配置项相关工具和资源；可选择开放的工具。

#mcp-server #otrs #api-integration

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "otrs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "build"
      ]
    }
  }
}

启动命令docker run -i --rm build

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocibuildstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

OTRS MCP 服务

用于集成 OTRS（开放工单请求系统）API 的模型上下文协议（MCP）服务。

通过标准化的 MCP 接口，提供对 OTRS 工单管理、配置项及其他 OTRS 功能的访问，让 AI 助手能够创建、搜索和管理工单及配置项。

功能

创建、读取、更新和搜索工单
访问工单历史记录和详细信息
管理配置项（CMDB）
会话管理和身份验证
为工单配置默认值
支持 Docker 容器化
支持 SSL/TLS，并可配置证书验证选项
为 AI 助手提供交互式工具

工具列表可配置，因此你可以选择要向 MCP 客户端提供哪些工具。

前提条件

OTRS 服务配置

使用此 MCP 服务之前，需要配置 OTRS 实例：

第 1 步：访问 OTRS 管理面板

URL：https://your-otrs-server/otrs/index.pl?Action=Admin
使用管理员凭据登录

第 2 步：配置 Web 服务

前往：系统管理 → Web 服务
创建或确认已有一个 Web 服务（例如“TestInterface”），并包含以下操作：
- ✅ SessionCreate
- ✅ TicketCreate
- ✅ TicketGet
- ✅ TicketSearch
- ✅ TicketUpdate
- ✅ TicketHistoryGet
- ✅ ConfigItemGet
- ✅ ConfigItemSearch

第 3 步：记下 Web 服务 URL

Web 服务 URL 的格式应如下：

https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/YourWebserviceName

第 4 步：确保用户权限

确保你的 OTRS 用户拥有以下操作所需的权限：

创建和更新工单
访问配置项
使用通用接口

用法

Docker（推荐）

使用 Docker 搭配 Claude Desktop 是运行 otrs-mcp 最简单的方式。如果尚未安装 Docker，可从 Docker 官方网站获取。

使用预构建镜像

你可以使用 GitHub Container Registry 中的预构建 Docker 镜像：

{
  "mcpServers": {
    "otrs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OTRS_BASE_URL=https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface",
        "-e",
        "OTRS_USERNAME=your-username",
        "-e",
        "OTRS_PASSWORD=your-password",
        "-e",
        "OTRS_VERIFY_SSL=false",
        "-e",
        "OTRS_DEFAULT_QUEUE=Raw",
        "-e",
        "OTRS_DEFAULT_STATE=new",
        "-e",
        "OTRS_DEFAULT_PRIORITY=3 normal",
        "ghcr.io/yourusername/otrs-mcp-server:latest"
      ]
    }
  }
}

本地构建

如果你希望在本地构建镜像：

# Clone the repository
git clone https://github.com/yourusername/otrs-mcp-server.git
cd otrs-mcp-server

# Build the Docker image
docker build -t otrs-mcp-server .

# Run the container
docker run --rm -i \
  -e OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface" \
  -e OTRS_USERNAME="your-username" \
  -e OTRS_PASSWORD="your-password" \
  -e OTRS_VERIFY_SSL="false" \
  otrs-mcp-server

使用 UV 运行

你也可以直接使用 UV 运行服务。首先，设置环境变量：

export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"
export OTRS_DEFAULT_QUEUE="Raw"
export OTRS_DEFAULT_STATE="new"
export OTRS_DEFAULT_PRIORITY="3 normal"
export OTRS_DEFAULT_TYPE="Unclassified"

然后编辑 Claude Desktop 配置文件，并添加服务配置：

{
  "mcpServers": {
    "otrs": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to otrs-mcp-server directory>",
        "run",
        "src/otrs_mcp/main.py"
      ],
      "env": {
        "OTRS_BASE_URL": "https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface",
        "OTRS_USERNAME": "your-username",
        "OTRS_PASSWORD": "your-password",
        "OTRS_VERIFY_SSL": "false"
      }
    }
  }
}

注意：如果你在 Claude Desktop 中看到 Error: spawn uv ENOENT，可能需要指定 uv 的完整路径，或在配置中设置环境变量 NO_UV=1。

环境变量

变量	必填	默认值	描述
`OTRS_BASE_URL`	✅	-	OTRS Web 服务的基础 URL
`OTRS_USERNAME`	✅	-	OTRS 用户名
`OTRS_PASSWORD`	✅	-	OTRS 密码
`OTRS_VERIFY_SSL`	❌	`false`	启用 SSL 证书验证
`OTRS_DEFAULT_QUEUE`	❌	`Raw`	新工单的默认队列
`OTRS_DEFAULT_STATE`	❌	`new`	新工单的默认状态
`OTRS_DEFAULT_PRIORITY`	❌	`3 normal`	新工单的默认优先级
`OTRS_DEFAULT_TYPE`	❌	`Unclassified`	新工单的默认类型

开发

欢迎贡献！如果您有任何建议或改进，请提交 issue 或拉取请求。

本项目使用 uv 管理依赖项。请按照适用于您平台的说明安装 uv：

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

随后，您可以创建虚拟环境并安装依赖项：

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

测试

测试您的 OTRS 连接和 API 功能：

# Set environment variables
export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"

# Run connectivity test
uv run python tests/connectivity_test.py

# Run API functionality test
uv run python tests/test_working_api.py

# Run debug diagnostics
uv run python tests/debug_test.py

本项目包含用于验证 OTRS 配置和 API 连通性的测试脚本。

使用 pytest 运行测试：

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

发布 Docker 镜像

要将 Docker 镜像发布到 GitHub Container Registry 以供公众使用：

前提条件

GitHub 账号，并拥有此项目的仓库
GitHub 个人访问令牌，且具有 write:packages 权限
本地已安装 Docker

分步发布

创建 GitHub 个人访问令牌：
- 前往 GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- 生成具有 write:packages 和 read:packages 权限的新令牌
- 安全保存该令牌

登录 GitHub Container Registry：

echo $GITHUB_TOKEN | docker login ghcr.io -u yourusername --password-stdin

构建并标记镜像：

# Build the image
docker build -t otrs-mcp-server .

# Tag for GitHub Container Registry
docker tag otrs-mcp-server ghcr.io/yourusername/otrs-mcp-server:latest
docker tag otrs-mcp-server ghcr.io/yourusername/otrs-mcp-server:v0.1.0

推送到 Registry：

# Push latest tag
docker push ghcr.io/yourusername/otrs-mcp-server:latest

# Push version tag
docker push ghcr.io/yourusername/otrs-mcp-server:v0.1.0

将软件包设为公开（可选）：
- 前往您的 GitHub 仓库
- 导航至 Packages 部分
- 点击您的软件包
- 前往 Package settings
- 将可见性更改为 Public

使用 GitHub Actions 自动发布

创建 .github/workflows/docker-publish.yml：

name: Build and Push Docker Image

on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

替代方案：Docker Hub

改为发布到 Docker Hub：

# Login to Docker Hub
docker login

# Tag for Docker Hub
docker tag otrs-mcp-server yourusername/otrs-mcp-server:latest
docker tag otrs-mcp-server yourusername/otrs-mcp-server:v0.1.0

# Push to Docker Hub
docker push yourusername/otrs-mcp-server:latest
docker push yourusername/otrs-mcp-server:v0.1.0

然后更新 Claude Desktop 配置，使用：

"ghcr.io/yourusername/otrs-mcp-server:latest"

或

"yourusername/otrs-mcp-server:latest"

可用工具

🎫 工单管理

create_ticket - 在 OTRS 中创建新工单
get_ticket - 获取特定工单的详细信息
search_tickets - 根据各种条件搜索工单
update_ticket - 更新现有工单的属性
get_ticket_history - 获取工单的完整历史记录

🔧 配置项（CMDB）

get_config_item - 获取配置项的详细信息
search_config_items - 搜索配置项

🔐 会话管理

create_session - 创建新的 OTRS 会话以进行身份验证

📊 资源

otrs://ticket/{ticket_id} - 直接访问工单数据
otrs://ticket/{ticket_id}/history - 访问工单历史记录
otrs://search/tickets - 查看近期工单概览
otrs://configitem/{config_item_id} - 访问配置项数据

故障排除

常见问题

SSL 证书错误：对于自签名证书，设置 OTRS_VERIFY_SSL=false
HTTP 301 重定向：如果您的 OTRS 服务会将 HTTP 重定向到 HTTPS，请确保使用 HTTPS URL
身份验证失败：请检查用户名、密码和 Web 服务配置
缺少操作：请检查 OTRS Web 服务是否包含所有必需操作

调试模式

运行调试脚本以诊断连接问题：

uv run python tests/debug_test.py

这将测试 HTTP 和 HTTPS 连接，并提供详细的错误信息。

可用配置示例

以下是一个可用配置示例，供您参考：

# Environment variables
export OTRS_BASE_URL="https://192.168.5.159/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="seasonpoon.admin"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"
export OTRS_DEFAULT_QUEUE="Raw"
export OTRS_DEFAULT_STATE="new"
export OTRS_DEFAULT_PRIORITY="3 normal"
export OTRS_DEFAULT_TYPE="Unclassified"

OTRS Webservice 操作

你的 OTRS webservice 应包含以下操作：

操作名称	控制器	描述
SessionCreate	Session::SessionCreate	创建身份验证会话
TicketCreate	Ticket::TicketCreate	创建新工单
TicketGet	Ticket::TicketGet	获取工单详情
TicketSearch	Ticket::TicketSearch	搜索工单
TicketUpdate	Ticket::TicketUpdate	更新现有工单
TicketHistoryGet	Ticket::TicketHistoryGet	获取工单历史
ConfigItemGet	ConfigItem::ConfigItemGet	获取配置项
ConfigItemSearch	ConfigItem::ConfigItemSearch	搜索配置项

许可证

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

OTRS MCP Server

关于 OTRS MCP Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

OTRS MCP 服务

功能

前提条件

OTRS 服务配置

第 1 步：访问 OTRS 管理面板

第 2 步：配置 Web 服务

第 3 步：记下 Web 服务 URL

第 4 步：确保用户权限

用法

Docker（推荐）

使用预构建镜像

本地构建

使用 UV 运行

环境变量

开发

测试

发布 Docker 镜像

前提条件

分步发布

使用 GitHub Actions 自动发布

替代方案：Docker Hub

可用工具

🎫 工单管理

🔧 配置项（CMDB）

🔐 会话管理

📊 资源

故障排除

常见问题

调试模式

可用配置示例

OTRS Webservice 操作

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？