Servidor MCP de OTRS

Un servidor Model Context Protocol (MCP) para la integración con la API de OTRS (Open Ticket Request System).

Esto proporciona acceso a la gestión de tickets de OTRS a través de interfaces MCP estandarizadas, lo que permite a los asistentes de IA crear, buscar y gestionar tickets.

Características

• Crear, leer, actualizar y buscar tickets

• Acceder al historial y a la información detallada de los tickets

• Valores predeterminados configurables para los tickets

• Soporte para contenedores Docker

• Soporte SSL/TLS con opciones de verificación de certificados

• Proporcionar herramientas interactivas para asistentes de IA

La lista de herramientas es configurable, por lo que puedes elegir qué herramientas quieres poner a disposición del cliente MCP.

Related MCP server: tickiti-mcp

Requisitos previos

Configuración del servidor OTRS

Antes de usar este servidor MCP, necesitas configurar tu instancia de OTRS.

Paso 1: Accede al panel de administración de OTRS

• URL: https://your-otrs-server/otrs/index.pl?Action=Admin

• Inicia sesión con tus credenciales de administrador

Paso 2: Configura los Web Services

1. Ve a: Administración del sistema → Web Services

2. Crea o verifica que tienes un servicio web (por ejemplo, TestInterface) con estas operaciones:

   • ✅ SessionCreate

   • ✅ TicketCreate

   • ✅ TicketGet

   • ✅ TicketSearch

   • ✅ TicketUpdate

   • ✅ TicketHistoryGet

Paso 3: Anota la URL de tu servicio web

La URL de tu servicio web debería tener un formato similar a:

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

Paso 4: Asegura los permisos del usuario

Asegúrate de que tu usuario de OTRS tiene los permisos adecuados para:

• Crear y actualizar tickets

• Acceder a los elementos de configuración

• Usar la interfaz genérica

Uso

Docker (recomendado)

La forma más fácil de ejecutar otrs-mcp con Claude Desktop es usando Docker. Si no tienes Docker instalado, puedes obtenerlo en el sitio web oficial de Docker.

Usar la imagen precompilada

Puedes usar la imagen Docker precompilada de GitHub Container Registry:

{
  "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/eduardoantoniojunior/otrs-mcp-server:latest"
      ]
    }
  }
}

Compilar localmente

Si prefieres compilar la imagen localmente:

# Clone the repository
git clone https://github.com/eduardoantoniojunior/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

Ejecutar con UV

Alternativamente, puedes ejecutar el servidor directamente con UV. Primero, configura tus variables de entorno:

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"

Después, edita el archivo de configuración de Claude Desktop y añade la configuración del servidor:

{
  "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"
      }
    }
  }
}

Nota: si ves Error: spawn uv ENOENT en Claude Desktop, puede que necesites especificar la ruta completa de uv o establecer la variable de entorno NO_UV=1 en la configuración.

Variables de entorno

Desarrollo

Las contribuciones son bienvenidas. Si tienes sugerencias o mejoras, abre un issue o crea una pull request.

Este proyecto tiene como objetivo Python 3.12 (ver requires-python en pyproject.toml) y está validado para su uso en producción en esa versión.

Este proyecto usa uv para gestionar las dependencias. Instala uv siguiendo las instrucciones de tu plataforma:

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

Instala Python 3.12 (si no lo tienes) y crea el entorno virtual con las dependencias fijadas:

# Install the interpreter (managed by uv)
uv python install 3.12

# Create the environment and install dependencies from uv.lock
uv sync --python 3.12 --extra dev

También puedes usar el flujo de trabajo clásico:

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

Pruebas

Prueba tu conexión con OTRS y la funcionalidad de la 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

El proyecto incluye scripts de prueba que ayudan a verificar tu configuración y la conectividad con la API de OTRS.

Ejecuta las pruebas con pytest:

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

# Run the tests
pytest

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

Publicar la imagen Docker

Para publicar la imagen Docker en GitHub Container Registry para de uso público:

Requisitos previos

1. Cuenta de GitHub con un repositorio para este proyecto

2. GitHub Personal Access Token con permiso write:packages

3. Docker instalado localmente

Publicación paso a paso

1. Genera un GitHub Personal Access Token:

   • Ve a GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)

   • Genera un nuevo token con permisos write:packages y read:packages

   • Guarda el token de forma segura

2. Inicia sesión en GitHub Container Registry:

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

3. Compila y etiqueta la imagen:

   # 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. Sube la imagen al registro:

   # 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. Haz público el paquete (opcional):

   • Ve a tu repositorio de GitHub

   • Navega a la sección Packages

   • Haz clic en tu paquete

   • Ve a Package settings

   • Cambia la visibilidad a Public

Publicación automatizada con GitHub Actions

Crea .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 }}

Alternativa: Docker Hub

Para publicar en Docker Hub en su lugar:

# 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

Luego actualiza la configuración de Claude Desktop para usar:

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

o

"yourusername/otrs-mcp-server:latest"

Herramientas disponibles

🎫 Gestión de tickets

• create_ticket - Crea un nuevo ticket en OTRS

• get_ticket - Obtén información detallada de un ticket específico

• search_tickets - Busca tickets según diferentes criterios

• update_ticket - Actualiza las propiedades de un ticket existente

• get_ticket_history - Obtén el historial completo de un ticket

📊 Recursos

• otrs://ticket/{ticket_id} - Acceso directo a los datos del ticket

• otrs://ticket/{ticket_id}/history - Acceso al historial del ticket

• otrs://search/tickets - Visión general de los tickets recientes

Solución de problemas

Problemas comunes

1. Errores de certificado SSL: Configura OTRS_VERIFY_SSL=false para certificados autofirmados.

2. Redirecciones HTTP 301: Asegúrate de usar URLs HTTPS si tu servidor OTRS redirige HTTP a HTTPS.

3. Fallos de autenticación: Verifica tu usuario, tu contraseña y la configuración del servicio web.

4. Operaciones que faltan: Comprueba que tu servicio web de OTRS incluye todas las operaciones requeridas.

Modo de depuración

Ejecuta el script de depuración para diagnosticar problemas de conexión:

uv run python tests/debug_test.py

Esto probará las conexiones HTTP y HTTPS y proporcionará información detallada sobre los errores.

Ejemplo de configuración que funciona

Para tu referencia, aquí tienes una configuración válida de ejemplo:

# 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"
export OTRS_DEFAULT_QUEUE="Raw"
export OTRS_DEFAULT_STATE="new"
export OTRS_DEFAULT_PRIORITY="3 normal"
export OTRS_DEFAULT_TYPE="Unclassified"

Operaciones del servicio web de OTRS

Tu servicio web de OTRS debe incluir estas operaciones:

Licencia

Apache-2.0