Otrs MCP Server

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服务

1. 导航到： 系统管理→ Web服务
2. 创建或验证您有一个具有以下操作的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，你可以从 .

使用预构建图像

您可以使用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",
        "",
        "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 在配置中。

环境变量

发展

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

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

先决条件

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

逐步发布

1. 创建GitHub个人访问令牌:

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

1. 登录GitHub容器注册表:

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

1. 构建并标记图像:

   # 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

1. 推送到注册表:

   # 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

1. 使包公开 （可选）：

- 转到您的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} -访问配置项数据

故障排除

常见问题

1. SSL证书错误：设置 OTRS_VERIFY_SSL=false 用于自签名证书
2. HTTP 301重定向：如果您的OTRS服务器将HTTP重定向到HTTPS，请确保您使用的是HTTPS URL
3. 身份验证失败：验证您的用户名、密码和Web服务配置
4. 缺失操作：检查您的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网络服务应包括以下操作：

许可证

麻省理工学院

______________________________________________________________________