内容
mcp-movidesk
[](https://github.com/ferronicardoso/mcp-movidesk/actions/workflows/docker-publish.yml)
[](https://github.com/ferronicardoso/mcp-movidesk/pkgs/container/mcp-movidesk)
[](package.json)
用于与 Movidesk 公共 API 进行交互的 MCP 服务器，通过自然语言，提供票务和人员/组织的接口，适用于 MCP 主机（Claude Desktop、VS Code、Cursor 等兼容工具）。
## 功能特点
- 票务列表、搜索、创建和更新（`/tickets` 和 `/tickets/past`）
- 在票务操作中上传附件（`/ticketFileUpload`）
- 人员/组织列表、搜索、创建和更新（`/persons`）
- 在列表工具中支持 OData 过滤器（`$filter`、`$select`、`$expand`、`$orderby`、`$top`、`$skip`）
- 错误处理，返回 Movidesk API 的错误信息
## 可用工具
| 工具 | 描述 |
|---|---|
| `list_tickets` | 列出最近 90 天更新的票务，可选 OData 过滤器 |
| `list_tickets_past` | 列出 90 天前更新的票务（`/tickets/past`） |
| `get_ticket` | 按 `id` 或 `protocol` 搜索票务 |
| `create_ticket` | 创建新票务 |
| `update_ticket` | 更新现有票务，包括通过 `actions` 添加备注/回复 |
| `upload_ticket_attachment` | 上传本地文件作为票务操作的附件 |
| `list_persons` | 列出人员/组织，可选 OData 过滤器 |
| `get_person` | 按 `id` 搜索人员/组织 |
| `create_person` | 创建新人员/组织 |
| `update_person` | 更新现有人员/组织 |
## 要求
- Node.js 18+
- Movidesk API 令牌（在 Movidesk中生成：设置 → 工作空间 → API 令牌）
## 配置
身份验证令牌可以通过环境变量或命令行参数提供。当两者都提供时，命令行参数优先。
| 变量/参数 | 必需 | 描述 |
|---|---|---|
| `MOVIDESK_TOKEN` | 是* | Movidesk API 令牌 |
| `--token` | 是* | `MOVIDESK_TOKEN` 的替代方案，通过命令行参数 |
\* 两者之一是必需的。
API 基本 URL（`https://api.movidesk.com/public/v1`）是固定的，无法配置。
**安全：** 建议通过 `env` 使用 `MOVIDESK_TOKEN` 进行连续使用。 `--token` 在进程列表（`ps`、任务管理器）中可见，仅建议进行临时手动测试。
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `MCP_TRANSPORT` | 否 | `stdio` | 传输模式：`stdio`（默认，适用于 `npx`/Claude Desktop/VS Code）或 `http`（Streamable HTTP，适用于 Docker/远程客户端，如 n8n） |
| `MCP_HTTP_PORT` | 否 | `3003` | HTTP 服务器端口（仅在 `MCP_TRANSPORT=http` 时使用） |
| `MCP_HTTP_HOST` | 否 | `0.0.0.0` | HTTP 服务器绑定地址（仅在 `MCP_TRANSPORT=http` 时使用） |
## 使用
### 直接从 GitHub 运行
```bash
npx github:ferronicardoso/mcp-movidesk
```
### Claude Desktop 配置
`%APPDATA%\\Claude\\claude_desktop_config.json`:
```json
{
"mcpServers": {
"movidesk": {
" "npx",
"args": ["github:ferronicardoso/mcp-movidesk"],
"env": {
"MOVIDESK_TOKEN": "您的令牌"
}
}
}
}
```
### VS Code MCP 配置
`.vscode/mcp.json`:
```json
{
"servers": {
"movidesk": {
"command": "npx",
"args": ["github:ferronicardoso/mcp-movidesk"],
"env": {
"MOVIDESK_TOKEN": "您的令牌"
}
}
}
}
```
### 使用 Docker 运行（HTTP 传输）
发布的镜像默认以 Streamable HTTP 模式运行，可用作远程 MCP 端点（例如，从 n8n 的 MCP 客户端工具节点或任何兼容 Streamable HTTP 的客户端）：
```bash
docker run -d --name mcp-movidesk \
-p 3003:3003 \
-e MOVIDESK_TOKEN=您的令牌 \
ghcr.io/ferronicardoso/mcpidesk:latest
```
MCP 端点可在 `http://localhost:3003/mcp` 访问。
## 本地开发
```bash clone https://github.com/ardoso/mcp-movidesk
cd mcp-movidesk
npm install
npm run build
```
启动编译后的服务器：
```bash
MOVIDESK_TOKEN=您的令牌
```
## 提交工作流程
本仓库版本化 `dist/`支持通过 `npx/repo` 使用。
使用 Husky `pre-commit` 钩子：
1. 编译 TypeScript（`npm run build`）
2. 添加生成的工件（`git add dist`）
手动回退：
```bash
npm run build
git add dist
```
## 安全注意事项
- 永远不要提交真实令牌或 `.env` 文件。
- 对于连续使用环境变量使用 `MOV_TOKEN`；避免在以外使用 `--token`。
- API 的 10 次/分钟限制在 7:01 至 18:59 之间生效；在此时间以外，访问不受限制。
