Skip to main content
Glama
Sign In
MCP Movidesk Server

MCP Movidesk Server

by raylann-lopes
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

đŸŽ« MCP Movidesk Server

Servidor MCP (Model Context Protocol) para gerenciamento de tickets do Movidesk, construĂ­do em TypeScript + Node.js.

Permite que agentes de IA criem, consultem, pesquisem e gerenciem tickets diretamente no Movidesk, sem precisar acessar a plataforma manualmente.

📋 Ferramentas Disponíveis

#

Ferramenta

Descrição

1

criar_ticket

Criar novo ticket com macro de suporte (atendimento/escalonamento)

2

consultar_ticket

Buscar detalhes completos de um ticket por ID

3

buscar_conhecimento

Pesquisar tickets resolvidos como base de conhecimento

4

adicionar_interacao

Adicionar comentårio/ação em ticket existente

5

listar_tickets_cliente

Listar tickets de um cliente por nome/email/CPF/CNPJ

6

alterar_status_ticket

Mudar status do ticket (Novo, Em atendimento, Resolvido, etc.)

7

atribuir_agente

Atribuir ticket a um agente ou equipe

Related MCP server: Xalantis MCP Server

🚀 Instalação

1. Instalar dependĂȘncias

cd c:\Users\Usuario\Documents\Mcp_Eagle
npm install

2. Configurar token da API

Copie o arquivo de exemplo e insira seu token:

copy .env.example .env

Edite o arquivo .env e substitua seu_token_aqui pelo seu token real:

MOVIDESK_TOKEN=seu_token_real_aqui

Onde encontrar o token: Movidesk > Configuração > Conta > Parùmetros > Aba Ambiente

3. Compilar o projeto

npm run build

⚙ Configuração no Antigravity

Adicione a seguinte configuração ao seu settings.json do Antigravity:

{
  "mcpServers": {
    "mcp-movidesk": {
      "command": "node",
      "args": ["c:\\Users\\Usuario\\Documents\\Mcp_Eagle\\dist\\index.js"],
      "env": {
        "MOVIDESK_TOKEN": "seu_token_aqui"
      }
    }
  }
}

đŸ§Ș Testes

Execute todos os testes:

npm test

Modo watch (re-executa ao salvar):

npm run test:watch

ïżœ Docker (Swarm & Portainer)

O projeto estå configurado para ser implantado facilmente através de Portainer/Docker Swarm com suporte a Traefik e HTTPS nativo via pacote Express.

Build da Imagem

Para criar a imagem Docker otimizada:

docker build -t mcp-movidesk-eagle:latest .

Deploy no Portainer (Stacks)

  1. Acesse seu Portainer.

  2. Navegue até Swarm > Stacks e clique em Add stack.

  3. Copie o conteĂșdo do arquivo docker-compose.yml e cole no Web Editor.

  4. Na seção Environment variables, adicione MOVIDESK_TOKEN com o seu token real.

  5. Clique em Deploy the stack.

A configuração utiliza o Traefik como proxy e vai publicar automaticamente em https://mcp.wizeflowsolutions.com/mcp.

🌐 Configuração Remota (via Domínio)

Para utilizar as ferramentas do MCP em clientes modernos ou em nuvem que suportam conexĂ”es via domĂ­nio (SSE - Server-Sent Events) como Dify, Flowise, Cursor ou LangChain, vocĂȘ informarĂĄ que o tipo de conexĂŁo Ă© remota.

O formato JSON para essas configuraçÔes:

{
  "mcpServers": {
    "mcp-movidesk-cloud": {
      "type": "sse",
      "url": "https://mcp.wizeflowsolutions.com/mcp"
    }
  }
}

Atenção: Em aplicativos puramente locais não adaptados para leitura web, utilize o método CLI fornecido na seção de "Configuração no Antigravity".

ïżœđŸ“ Estrutura do Projeto

src/
├── index.ts                     # Ponto de entrada (stdio transport)
├── servidor-mcp.ts              # Registra as 7 ferramentas
├── cliente-movidesk/
│   ├── api.ts                   # Cliente HTTP com rate-limiting
│   └── tipos.ts                 # Tipos TypeScript (interfaces/enums)
├── ferramentas/
│   ├── criar-ticket.ts          # Criar ticket com macro
│   ├── consultar-ticket.ts      # Consultar ticket por ID
│   ├── buscar-conhecimento.ts   # Base de conhecimento
│   ├── adicionar-interacao.ts   # Adicionar interação
│   ├── listar-tickets.ts        # Listar tickets do cliente
│   ├── alterar-status.ts        # Alterar status
│   └── atribuir-agente.ts       # Atribuir agente
└── utilidades/
    ├── formatador-html.ts       # Markdown → HTML
    ├── validacoes.ts            # ValidaçÔes (CPF, CNPJ, email)
    └── macros-suporte.ts        # Templates HTML de macros
testes/
├── formatador-html.test.ts
├── validacoes.test.ts
├── api-cliente.test.ts
└── ferramentas.test.ts

🔧 Desenvolvimento

# Executar em modo desenvolvimento (com tsx)
npm run dev

# Compilar TypeScript
npm run build

# Executar versĂŁo compilada
npm start

📄 Licença

MIT

Available Tools

8 tools
adicionar_interacaoA

Adiciona uma interação (comentĂĄrio/ação) em um ticket existente do Movidesk. O conteĂșdo Ă© automaticamente formatado em HTML. IMPORTANTE: Pergunte ao usuĂĄrio o nĂșmero do ticket. Se o usuĂĄrio mencionar o nome do cliente, utilize primeiro a ferramenta 'consultar_cliente' e 'listar_tickets_cliente' para achar o ID Exato do ticket.

Inputs: conteudo (required), ticketId (required), publico, nomeAutor.

alterar_status_ticketA

Altera o status de um ticket no Movidesk. Status disponĂ­veis: 'Novo', 'Em atendimento', 'Parado', 'Resolvido', 'Cancelado', 'Fechado'. Alguns status como 'Parado' e 'Cancelado' exigem justificativa obrigatĂłria.

Inputs: ticketId (required), novoStatus (required), justificativa.

atribuir_agenteA

Atribui um ticket a um agente ou equipe especĂ­fica no Movidesk, alterando o responsĂĄvel (owner) do ticket. Use para escalonar ou redistribuir tickets entre a equipe.

Inputs: agenteId (required), ticketId (required), equipe, nomeAgente.

buscar_conhecimentoA

Pesquisa na base de conhecimento do Movidesk (tickets resolvidos/fechados) para encontrar soluçÔes de problemas similares. Receba a descrição do problema, busque tickets relacionados e retorne instruçÔes de resolução. Funciona como uma base de conhecimento viva da equipe de suporte.

Inputs: descricaoProblema (required), incluirInteracoes, quantidadeResultados.

consultar_clienteA

Busca e consulta se um cliente existe na base de contatos do sistema (Pessoas/Empresas), buscando pelo Nome (Razão social), Email ou CPF/CNPJ. Sempre use essa função se o usuårio solicitar para checar um cliente, antes de abrir tickets.

Inputs: nomeCliente, emailCliente, documentoCliente.

consultar_ticketA

Busca os detalhes completos de um ticket do Movidesk pelo seu ID numérico. Retorna todas as informaçÔes incluindo status, responsåvel, cliente, interaçÔes, campos personalizados e datas.

Inputs: ticketId (required).

criar_ticketA

Cria um novo ticket no Movidesk com macro de suporte formatada em HTML. Ideal para registrar atendimentos apĂłs o suporte. Suporta macros de atendimento e escalonamento. SEMPRE use a ferramenta 'consultar_cliente' ANTES para pegar o email ou id do cliente (vocĂȘ NÃO PODE tentar adivinhar ou embutir um CPF/CNPJ ou Nome, a api apenas suportarĂĄ dados reais vindos da consulta do cliente no movidesk)

Inputs: assunto (required), descricao (required), emailCliente (required), tags, +16 more.

listar_tickets_clienteA

Lista os Ășltimos tickets de um cliente especĂ­fico, filtrando por nome (razĂŁo social), email ou documento (CPF/CNPJ). Útil para verificar histĂłrico e evitar duplicidade antes de criar um novo ticket.

Inputs: quantidade, nomeCliente, emailCliente, documentoCliente.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog


    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a clear, distinct resource and action: ticket creation, ticket retrieval, knowledge search, interaction addition, ticket listing by client, client lookup, status change, and agent assignment. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in Portuguese, using snake_case throughout (e.g., criar_ticket, consultar_ticket, alterar_status_ticket). The naming is predictable and readable, with no mixed conventions.

    Tool Count5/5

    With 8 tools, the server provides a focused set that covers the core ticket management workflow without being bloated or too thin. Each tool serves a distinct function, making the count well-scoped for the domain.

    Completeness4/5

    The core ticket lifecycle is covered: create, retrieve, list by client, add interactions, change status, and assign. Minor gaps include lack of a general list-all-tickets endpoint and no update/delete for tickets, but these are workable for a support-focused toolset.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers