mcp-movidesk

MCP server para interação com a API pública do Movidesk via linguagem natural, expondo operações de tickets e de pessoas/organizações a hosts MCP (Claude Desktop, VS Code, Cursor e compatíveis).

Features

• Listagem, busca, criação e atualização de tickets (/tickets e /tickets/past)

• Upload de anexos em ações de ticket (/ticketFileUpload)

• Listagem, busca, criação e atualização de pessoas/organizações (/persons)

• Suporte a filtros OData ($filter, $select, $expand, $orderby, $top, $skip) nas ferramentas de listagem

• Tratamento de erro que repassa o corpo de erro retornado pela API do Movidesk

Related MCP server: OTRS MCP Server

Available Tools

Requirements

• Node.js 18+

• Token de API do Movidesk (gerado no painel admin do Movidesk: Configurações → Espaço de trabalho → Token de API)

Configuration

O token de autenticação pode ser informado por variável de ambiente ou por argumento de linha de comando. Quando os dois forem informados, o argumento prevalece.

* Um dos dois é obrigatório.

A URL base da API (https://api.movidesk.com/public/v1) é fixa e não é configurável.

Segurança: prefira MOVIDESK_TOKEN via env para uso contínuo. --token fica visível em listagens de processo (ps, gerenciador de tarefas) e é recomendado apenas para testes manuais pontuais.

Usage

Run directly from GitHub

npx github:ferronicardoso/mcp-movidesk

Claude Desktop configuration

%APPDATA%\\Claude\\claude_desktop_config.json:

{
  "mcpServers": {
    "movidesk": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-movidesk"],
      "env": {
        "MOVIDESK_TOKEN": "seu-token-aqui"
      }
    }
  }
}

VS Code MCP configuration

.vscode/mcp.json:

{
  "servers": {
    "movidesk": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-movidesk"],
      "env": {
        "MOVIDESK_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Rodando com Docker (transporte HTTP)

A imagem publicada roda em modo Streamable HTTP por padrão, para uso como endpoint MCP remoto (ex.: a partir do node MCP Client Tool do n8n ou qualquer cliente compatível com Streamable HTTP):

docker run -d --name mcp-movidesk \
  -p 3003:3003 \
  -e MOVIDESK_TOKEN=seu-token-aqui \
  ghcr.io/ferronicardoso/mcp-movidesk:latest

O endpoint MCP fica disponível em http://localhost:3003/mcp.

Local Development

git clone https://github.com/ferronicardoso/mcp-movidesk
cd mcp-movidesk
npm install
npm run build

Start the compiled server:

MOVIDESK_TOKEN=seu-token-aqui npm start

Build and Commit Workflow

Este repositório versiona dist/ intencionalmente, para suportar o uso via npx github:user/repo.

O projeto usa um hook Husky pre-commit para:

1. compilar TypeScript (npm run build)

2. adicionar os artefatos gerados (git add dist)

Fallback manual:

npm run build
git add dist

Security Notes

• Nunca commite o token real ou arquivos .env.

• Use MOVIDESK_TOKEN via ambiente para uso contínuo; evite --token fora de testes pontuais.

• O limite de 10 requisições/minuto da API vale das 7:01 às 18:59; fora desse horário o acesso é irrestrito.