MCP Server for Movidesk

MCP server for interacting with the Movidesk public API via natural language, exposing ticket and person/organization operations to MCP hosts (Claude Desktop, VS Code, Cursor, and compatible clients).

Features

• List, search, create, and update tickets (/tickets and /tickets/past)

• Upload attachments to ticket actions (/ticketFileUpload)

• List, search, create, and update persons/organizations (/persons)

• OData filter support ($filter, $select, $expand, $orderby, $top, $skip) on listing tools

• Error handling that forwards the error body returned by the Movidesk API

Related MCP server: Gorgias MCP Server

Available Tools

Requirements

• Node.js 18+

• Movidesk API token (generated in the Movidesk admin panel: Settings → Workspace → API Token)

Configuration

The authentication token can be provided via environment variable or command-line argument. When both are provided, the argument takes precedence.

* One of the two is required.

The API base URL (https://api.movidesk.com/public/v1) is fixed and not configurable.

Security: prefer MOVIDESK_TOKEN via env for continuous use. --token is visible in process listings (ps, task manager) and is recommended only for one-off manual testing.

Usage

Run directly from GitHub

npx github:ferronicardoso/mcp-movidesk

Claude Code (CLI)

claude mcp add movidesk --scope user -- npx -y github:ferronicardoso/mcp-movidesk

--scope controls where the server registration is stored:

Environment variables can be passed with repeated --env KEY=VALUE flags before the --, e.g.:

Bash (Linux/macOS/WSL):

claude mcp add movidesk --scope user \
  --env MOVIDESK_TOKEN=your-token-here \
  -- npx -y github:ferronicardoso/mcp-movidesk

PowerShell:

claude mcp add movidesk --scope user `
  --env MOVIDESK_TOKEN=your-token-here `
  -- npx -y github:ferronicardoso/mcp-movidesk

Codex CLI

Bash (Linux/macOS/WSL):

codex mcp add movidesk \
  --env MOVIDESK_TOKEN=your-token-here \
  npx -- -y github:ferronicardoso/mcp-movidesk

PowerShell:

codex mcp add movidesk `
  --env MOVIDESK_TOKEN=your-token-here `
  npx -- -y github:ferronicardoso/mcp-movidesk

This registers the server in ~/.codex/config.toml. To remove it, run codex mcp remove movidesk.

Claude Desktop configuration

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

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

VS Code MCP configuration

.vscode/mcp.json:

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

Run with Docker (HTTP transport)

The published image runs in Streamable HTTP mode by default, for use as a remote MCP endpoint (e.g. from n8n's MCP Client Tool node or any Streamable HTTP-compatible client):

Bash (Linux/macOS/WSL):

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

PowerShell:

docker run -d --name mcp-movidesk `
  -p 3003:3003 `
  -e MOVIDESK_TOKEN=your-token-here `
  ghcr.io/ferronicardoso/mcp-movidesk:latest

The MCP endpoint is then available at 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=your-token-here npm start

Build and Commit Workflow

This repository intentionally tracks dist/ to support npx github:user/repo usage.

The project uses a Husky pre-commit hook to:

1. build TypeScript (npm run build)

2. stage generated artifacts (git add dist)

Manual fallback:

npm run build
git add dist

Security Notes

• Never commit the real token or .env files.

• Use MOVIDESK_TOKEN via environment for continuous use; avoid --token outside of one-off testing.

• The API's 10 requests/minute limit applies from 7:01 AM to 6:59 PM; outside that window access is unrestricted.

License

MIT © Raphael Augusto Ferroni Cardoso