OTRS MCP Server

OTRS MCP サーバー

OTRS（Open Ticket Request System）API 統合用のModel Context Protocol（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 サービスを設定する

1. System Administration → Web Services に移動します
2. 次の操作を含む 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 ユーザーに次の操作に必要な権限があることを確認します：

• チケットの作成と更新
• 構成アイテムへのアクセス
• Generic Interface の使用

使用方法

Docker（推奨）

Claude Desktop で otrs-mcp を実行する最も簡単な方法は、Docker を使用することです。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 に公開して、一般に利用できるようにします。

前提条件

1. GitHub アカウントと、このプロジェクト用のリポジトリ
2. write:packages権限を持つGitHub Personal Access Token
3. ローカルにインストールされたDocker

公開手順

1. GitHub Personal Access Token を作成する：

   • GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) に移動します
   • write:packagesとread:packages権限を持つ新しいトークンを生成します
   • トークンを安全に保存します

2. GitHub Container Registry にログインする：

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

3. イメージをビルドしてタグ付けする：

   # 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
   

4. レジストリにプッシュする：

   # 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
   

5. パッケージを公開する（任意）：

   • 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} - 構成アイテムのデータにアクセスします

トラブルシューティング

よくある問題

1. SSL 証明書エラー：自己署名証明書の場合は、OTRS_VERIFY_SSL=falseを設定します
2. HTTP 301 リダイレクト：OTRS サーバーが HTTP から HTTPS にリダイレクトする場合は、HTTPS URL を使用していることを確認します
3. 認証エラー：ユーザー名、パスワード、Web サービスの設定を確認します
4. 操作の不足：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 Web サービスの操作

OTRS Web サービスには、次の操作を含める必要があります。

操作名	コントローラー	説明
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

---