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)
• Download ticket attachments by hash (/storage/download), inline or saved to disk
• 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

Available Tools

Tool	Description
list_tickets	Lists tickets updated in the last 90 days, with optional OData filters
list_tickets_past	Lists tickets last updated more than 90 days ago (/tickets/past)
get_ticket	Fetches a ticket by id or protocol
create_ticket	Creates a new ticket
update_ticket	Updates an existing ticket, including notes/replies via actions
upload_ticket_attachment	Uploads a local file as an attachment to a ticket action
download_ticket_attachment	Downloads an attachment by its hash (path in actions[].attachments[]); returns it inline (up to 5 MB) or saves it to destinationPath
list_persons	Lists persons/organizations, with optional OData filters
get_person	Fetches a person/organization by id
create_person	Creates a new person/organization
update_person	Updates an existing person/organization

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.

Variable / Argument	Required	Description
MOVIDESK_TOKEN	Yes*	Movidesk API token
--token	Yes*	Alternative to MOVIDESK_TOKEN, via command-line argument

* 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.

Variable	Required	Default	Description
MCP_TRANSPORT	No	stdio	Transport mode: stdio (default, for npx/Claude Desktop/VS Code) or http (Streamable HTTP, for Docker/remote clients such as n8n)
MCP_HTTP_PORT	No	3003	Port for the HTTP server (only used when MCP_TRANSPORT=http)
MCP_HTTP_HOST	No	0.0.0.0	Bind address for the HTTP server (only used when MCP_TRANSPORT=http)

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:

Scope	Stored in	Visible to
local (default)	project-local, untracked	only you, only in this project
project	.mcp.json at the project root	anyone who clones the repo (commit it to share)
user	your global Claude Code config	you, across every project

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