OTRS MCP Server

┌──────────────────────────┐       ┌──────────────────────────┐
│   Agente IA              │       │   Navegador Admin        │
│ (Claude Desktop, Python) │       │ https://seu-dominio       │
└──────────┬───────────────┘       └──────────┬───────────────┘
           │ HTTPS + API Key                   │ HTTPS + JWT
           ▼                                   ▼
┌──────────────────────────────────────────────────────────────┐
│          Nginx (SSL via Certbot/Let's Encrypt)               │
│          + Fail2ban (protecao contra brute-force)            │
│          Porta 443 — Reverse Proxy                           │
└──────┬────────────────────┬────────────────────┬─────────────┘
       │ /mcp               │ /api/*             │ /
       ▼                    ▼                    ▼
┌────────────┐       ┌────────────┐       ┌────────────┐
│ MCP Server │       │  API REST  │       │  Frontend  │
│  (FastMCP) │       │ (FastAPI)  │       │  (React)   │
│ 127.0.0.1  │       │ 127.0.0.1  │       │ 127.0.0.1  │
│   :8001    │       │   :3000    │       │   :8080    │
└─────┬──────┘       └──────┬─────┘       └────────────┘
      │                     │
      └──────────┬──────────┘
                 ▼
      ┌──────────────────────┐       ┌──────────────────────┐
      │   SQLite (WAL)       │       │  OTel Collector       │
      │  /data/otrs-mcp.db   │       │  → Tempo / Mimir      │
      └──────────┬───────────┘       └───────────────────────┘
                 ▼
      ┌──────────────────────┐
      │   Servidor OTRS      │
      │ (Generic Interface)  │
      └──────────────────────┘

git clone https://github.com/eduardoantoniojunior/otrs-mcp-server.git
cd otrs-mcp-server
cp .env.example .env

# OTRS (obrigatorio)
OTRS_BASE_URL=https://seu-otrs/otrs/nph-genericinterface.pl/Webservice/MCPConnector
OTRS_USERNAME=seu-usuario
OTRS_PASSWORD=sua-senha

# Seguranca (obrigatorio em producao)
OTRS_ENV=production
OTRS_JWT_SECRET=gere-com-python-c-import-secrets-print-secrets-token-hex-32
OTRS_ADMIN_USER=admin
OTRS_ADMIN_PASSWORD=MUDE_ESTA_SENHA

# CORS (ajuste para seu dominio)
OTRS_CORS_ORIGINS=https://seu-dominio

docker compose up -d --build

docker compose ps
curl -s http://127.0.0.1:3000/api/health
curl -s http://127.0.0.1:8080 | head -5

sudo cp nginx/mcp.conf /etc/nginx/sites-available/mcp.conf
sudo ln -s /etc/nginx/sites-available/mcp.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d seu-dominio

curl https://seu-dominio/api/health

VITE_BASE_PATH=/otrs/

docker compose build frontend
docker compose up -d

sudo cp nginx/mcp.conf /etc/nginx/sites-available/mcp.conf
sudo nginx -t && sudo systemctl reload nginx

sudo cp deploy/otrs-mcp.service /etc/systemd/system/otrs-mcp.service
sudo systemctl daemon-reload
sudo systemctl enable otrs-mcp
sudo systemctl start otrs-mcp

sudo systemctl status otrs-mcp              # Status
sudo systemctl restart otrs-mcp             # Restart
sudo journalctl -u otrs-mcp -f              # Logs tempo real
sudo journalctl -u otrs-mcp --since "1h"    # Logs recentes

sudo apt install fail2ban
sudo cp deploy/fail2ban/jail.local /etc/fail2ban/jail.local
sudo cp deploy/fail2ban/filter.d/* /etc/fail2ban/filter.d/
sudo systemctl restart fail2ban
sudo systemctl enable fail2ban

sudo fail2ban-client status                           # Listar jails
sudo fail2ban-client status otrs-mcp-login            # IPs banidos
sudo fail2ban-client set otrs-mcp-login unbanip 1.2.3.4  # Desbanir

chmod +x deploy/deploy.sh deploy/backup.sh deploy/healthcheck.sh

# Backup diario as 3h
(crontab -l 2>/dev/null; echo "0 3 * * * /opt/otrs-mcp-server/deploy/backup.sh >> /var/log/otrs-mcp-backup.log 2>&1") | crontab -

# Health check a cada 5 minutos
(crontab -l 2>/dev/null; echo "*/5 * * * * /opt/otrs-mcp-server/deploy/healthcheck.sh") | crontab -

sudo cp deploy/otrs-mcp.logrotate /etc/logrotate.d/otrs-mcp

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}

HEALTHCHECK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ

./deploy/deploy.sh --pull    # Git pull + build + restart + healthcheck
./deploy/deploy.sh           # Apenas rebuild + restart

{
  "mcpServers": {
    "otrs": {
      "url": "https://seu-dominio/mcp",
      "headers": {
        "Authorization": "Bearer sk-otrs-sua-api-key-aqui"
      }
    }
  }
}

{
  "mcpServers": {
    "otrs": {
      "url": "https://mcp.dominio.com/otrs/mcp",
      "headers": {
        "Authorization": "Bearer sk-otrs-sua-api-key-aqui"
      }
    }
  }
}

{
  "servers": {
    "otrs": {
      "type": "http",
      "url": "https://seu-dominio/mcp",
      "headers": {
        "Authorization": "Bearer sk-otrs-sua-api-key-aqui"
      }
    }
  }
}

from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession

async def main():
    headers = {"Authorization": "Bearer sk-otrs-sua-api-key"}
    async with streamablehttp_client(
        "https://seu-dominio/mcp", headers=headers
    ) as (r, w, _):
        async with ClientSession(r, w) as session:
            await session.initialize()
            tools = await session.list_tools()
            result = await session.call_tool(
                "search_tickets",
                arguments={"state": "new", "limit": 5}
            )

{
  "mcpServers": {
    "otrs": {
      "command": "uv",
      "args": ["run", "python", "-m", "otrs_mcp.main"],
      "cwd": "/caminho/para/otrs-mcp-server",
      "env": {
        "OTRS_BASE_URL": "https://seu-otrs/otrs/nph-genericinterface.pl/Webservice/MCPConnector",
        "OTRS_USERNAME": "usuario",
        "OTRS_PASSWORD": "senha",
        "OTRS_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Authorization: Bearer <api-key-ou-jwt>

Backend (api/mcp) ──[gRPC:4317]──→ OTel Collector ──[OTLP HTTP]──→ Tempo/Mimir
Frontend (browser) ──[HTTP:4318]──→ OTel Collector ──[OTLP HTTP]──→ Tempo/Mimir

OTEL_TEMPO_ENDPOINT=http://172.31.x.x:4318
VITE_OTEL_ENDPOINT=https://seu-dominio/otel

docker compose down
docker compose up -d --build

sudo cp nginx/mcp.conf /etc/nginx/sites-available/mcp.conf
sudo nginx -t && sudo systemctl reload nginx

TraceQL: { resource.service.name = "otrs-mcp-api" }

otrs-mcp-server/
├── src/otrs_mcp/                # Pacote Python principal
│   ├── __init__.py              # API publica (v0.2.0)
│   ├── main.py                  # Entry point MCP (stdio/http)
│   ├── config.py                # Configuracao (pydantic-settings)
│   ├── client.py                # Cliente HTTP OTRS com retry + asyncio.Lock
│   ├── tools.py                 # 5 Tools MCP com validacao
│   ├── resources.py             # 3 Resources MCP
│   ├── api.py                   # Backend REST (FastAPI) com audit trail
│   ├── auth.py                  # JWT (iat/jti) + API key + rate limiting
│   ├── database.py              # SQLite WAL (schema + CRUD + metricas diarias)
│   ├── validation.py            # Validacao centralizada (ticket_id)
│   ├── activity.py              # Monitoramento de atividade (JSON)
│   ├── constants.py             # Prioridades e estados validos
│   ├── exceptions.py            # Excecoes customizadas
│   └── routes/
│       └── admin.py             # Login (brute-force SQLite), refresh, keys, users, audit, metrics
├── frontend/                    # React 19 + TypeScript + TailwindCSS
│   ├── src/
│   │   ├── pages/               # Login, ApiKeys, AuditLog, LoginAudit, Settings, ClientWizard
│   │   ├── components/          # Dashboard (graficos CSS), Layout
│   │   ├── contexts/            # AuthContext (JWT refresh automatico)
│   │   ├── hooks/               # useTickets, useHealth, etc.
│   │   ├── services/api.ts      # HTTP client (timeout, logout centralizado, subpath-aware)
│   │   ├── telemetry.ts         # OpenTelemetry Web SDK (fetch + document load)
│   │   └── types/               # TypeScript types
│   ├── Dockerfile               # Node 20 build + Nginx 1.27 Alpine serve
│   ├── nginx.conf               # Security headers (CSP, X-Frame-Options, etc.)
│   ├── vite.config.ts           # Vite config (base path via VITE_BASE_PATH)
│   └── package.json             # React 19, Vite 6, TanStack Query 5, OTel Web SDK
├── nginx/
│   └── mcp.conf                 # Nginx vhost (MODO 1: raiz, MODO 2: subpath comentado)
├── otel/
│   └── otel-collector.yaml      # Config OTel Collector (OTLP → Tempo/Mimir)
├── deploy/
│   ├── otrs-mcp.service         # Systemd service unit
│   ├── deploy.sh                # Script deploy (pull + build + healthcheck)
│   ├── backup.sh                # Backup SQLite (sqlite3.backup, gzip, 7 dias)
│   ├── healthcheck.sh           # Health check externo com webhook de alerta
│   ├── otrs-mcp.logrotate       # Log rotation para Docker
│   └── fail2ban/
│       ├── jail.local           # Config fail2ban (3 jails)
│       └── filter.d/
│           ├── otrs-mcp-login.conf    # Filtro login brute-force
│           ├── otrs-mcp-api.conf      # Filtro API abuse
│           └── nginx-botsearch.conf   # Filtro bot/scanner
├── tests/
│   ├── unit/                    # 41 testes unitarios (pytest)
│   └── integration/             # Testes de integracao
├── docker-compose.yml           # 4 servicos (api, mcp, frontend, otel-collector)
├── Dockerfile                   # MCP server (python:3.12.8, non-root, OTel zero-code)
├── Dockerfile.api               # API REST (python:3.12.8, non-root, OTel zero-code)
├── pyproject.toml               # Dependencias, build, CLI scripts
├── .env.example                 # Template de variaveis
└── AGENTS.md                    # Guia para agentes de IA

git clone https://github.com/eduardoantoniojunior/otrs-mcp-server.git
cd otrs-mcp-server

# Python (backend)
uv sync --extra dev

# Frontend
cd frontend && npm ci

# Unitarios (41 testes)
uv run pytest tests/unit/ -v

# Com cobertura
uv run pytest tests/unit/ --cov=src/otrs_mcp --cov-report=term-missing

uv run black src/
uv run isort src/
uv run mypy src/

# API REST (porta 3000)
uv run uvicorn otrs_mcp.api:app --port 3000 --reload

# MCP Server (porta 8001)
OTRS_MCP_TRANSPORT=http uv run python -m otrs_mcp.main

# Frontend (porta 5173, hot reload)
cd frontend && npm run dev

otrs-mcp-server   # Inicia o MCP server
otrs-mcp-api      # Inicia a API REST

docker compose logs -f                # Todos os containers
docker compose logs -f api            # API REST
docker compose logs -f mcp-server     # MCP Server
docker compose logs -f frontend       # Frontend
docker compose logs -f otel-collector # OpenTelemetry Collector
sudo journalctl -u otrs-mcp -f       # Systemd service
sudo tail -f /var/log/nginx/error.log          # Nginx
sudo fail2ban-client status otrs-mcp-login     # Fail2ban