使用说明

OTRS MCP服务器

A. 模型上下文协议（MCP）服务器，用于OTRS（开放式票据请求系统）API集成。

这通过标准化的MCP接口提供了对OTRS票证管理、配置项和其他OTRS功能的访问，允许AI助手创建、搜索和管理票证和配置项。

特性

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

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

先决条件

OTRS服务器配置

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

步骤1：访问OTRS管理面板

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

步骤2：配置Web服务

导航到： 系统管理→ Web服务
创建或验证您有一个具有以下操作的Web服务（例如“TestInterface”）：
- ✅ 会话创建
- ✅ TicketCreate
- ✅ 票务
- ✅ 票务搜索
- ✅ 票务更新
- ✅ 票务历史获取
- ✅ 配置项获取
- ✅ 配置项搜索

步骤3：记下您的Web服务URL

您的Web服务URL应该如下所示：

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

步骤4：确保用户权限

确保您的OTRS用户对以下内容具有适当的权限：

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

用法

Docker（推荐）

运行otrs-mcp的最简单方法克劳德桌面正在使用Docker。如果你没有安装Docker，你可以从 Docker官方网站.

使用预构建图像

您可以使用GitHub容器注册表中的预构建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"
      }
    }
  }
}

注意：如果你看到 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`	新票的默认类型

发展

欢迎投稿！如果您有任何建议或改进，请打开问题或提交拉取请求。

此项目使用 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容器注册表供公众使用：

先决条件

GitHub账号 具有此项目的存储库
GitHub个人访问令牌 随着 write:packages 许可
码头工人 本地安装

逐步发布

创建GitHub个人访问令牌:
- 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
- 使用生成新令牌 write:packages 和 read:packages 权限
- 安全保存令牌

登录GitHub容器注册表:

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

推送到注册表:

# 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存储库
- 导航到“包”部分
- 点击您的包裹
- 转到包设置
- 将可见性更改为公共

使用GitHub操作自动发布

创建 .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网络服务是否包括所有必需的操作

调试模式

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

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 Web服务操作

您的OTRS网络服务应包括以下操作：

操作名称	控制器	描述
SessionCreate	会话：：SessionCreate	创建身份验证会话
TicketCreate	Ticket:：TicketCreate	创建新票
TicketGet	Ticket:：TicketGet	Retrieve Ticket details
票务搜索	票务：：票务搜索	搜索门票
票务更新	票务：：票务更新	更新现有票务
TicketHistory获取	门票：：TicketHistory获得	获取门票历史
ConfigItemGet	配置项：：配置项获取	检索配置项
ConfigItemSearch	配置项：：配置项搜索	搜索配置项

许可证

麻省理工学院

使用说明

OTRS MCP服务器

特性

先决条件

OTRS服务器配置

步骤1：访问OTRS管理面板

步骤2：配置Web服务

步骤3：记下您的Web服务URL

步骤4：确保用户权限

用法

Docker（推荐）

使用预构建图像

在当地建设

使用UV运行

环境变量

发展

测试

发布Docker镜像

先决条件

逐步发布

使用GitHub操作自动发布

替代方案：Docker Hub

可用工具

🎫 票务管理

🔧 配置项（CMDB）

🔐 会话管理

📊 资源

故障排除

常见问题

调试模式

示例工作配置

OTRS Web服务操作

许可证

相关 MCP

实时网络搜索服务

图像生成服务

滴滴出行MCP服务

GraphQL API交互服务

DNS分析MCP服务器

LLM增强工具包