Teamdesk MCP V2

TeamDesk MCP服务器

MCP（模型上下文协议）服务器 TeamDesk 数据库。连接 克劳德 （网络、桌面和移动）， 克劳德代码，或任何MCP-兼容客户端到TeamDesk REST API v2。

特性

• 11工具 涵盖所有TeamDesk CRUD操作+搜索+文档生成
• 使用 任何TeamDesk数据库 --只需提供您的令牌和数据库ID
• 两种部署模式：

- 本地 (server.py)--通过stdio在用户的计算机上运行 - 远程 (deploy/server_sse.py)--具有OAuth 2.0、流式HTTP、速率限制和缓存的多用户服务器

• 带重音的表/列名的正确URL编码（葡萄牙语、西班牙语等）
• 超时处理，自动重试（55秒超时，2次回退重试）
• 通过输入消毒防止过滤器注射
• 用于请求计时和调试的Stderr日志记录

需求

• Python 3.10+
• A. TeamDesk REST API令牌 （生成位置：TeamDesk>设置>集成>REST API>令牌）
• 你的 TeamDesk数据库ID （在TeamDesk URL中可见： teamdesk.net/secure/db/XXXXX)

安装

选项1：远程连接器（推荐）

无需本地安装。 直接从claude.ai连接-自动在网络、桌面和移动设备上工作。

当您在claude.ai上添加自定义连接器时，它会自动同步到claude Desktop和移动设备。一个设置涵盖所有平台。

1. 让管理员创建访问密钥（请参阅 远程部署)
2. 首选 claude.ai > 设置 > 集成 > 添加自定义连接器
3. 输入名称（例如。， TeamDesk)以及服务器URL： https://your-server.com/m/{your_key}/sse
4. 点击 配置 >批准访问
5. 完成--适用于网络、桌面和移动设备

选项2：本地安装程序（Windows）

1. 下载 install.bat, server.py，以及 requirements.txt 来自此repo
2. 将它们放在同一个文件夹中
3. 跑 install.bat
4. 按照提示操作（它将询问您的令牌和数据库ID）
5. 重新启动克劳德桌面

选项3：本地安装程序（Linux/Mac）

1. 克隆并运行：

git clone https://github.com/Danielbluz/teamdesk-mcp-v2.git
cd teamdesk-mcp-v2
bash install.sh

1. 按照提示操作
2. 重新启动克劳德桌面

选项4：手动设置

git clone https://github.com/Danielbluz/teamdesk-mcp-v2.git
cd teamdesk-mcp-v2
pip install -r requirements.txt

然后添加到您的客户端配置中（请参阅下一节）。

配置

克劳德桌面（本地模式）

编辑 claude_desktop_config.json:

• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• 雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "teamdesk": {
      "command": "python",
      "args": ["C:\\path\\to\\server.py"],
      "env": {
        "TEAMDESK_API_TOKEN": "your_token_here",
        "TEAMDESK_DATABASE_ID": "your_database_id"
      }
    }
  }
}

克劳德代码

增添 .claude/.mcp.json 在您的项目或 ~/.claude/.mcp.json 全球地：

{
  "mcpServers": {
    "teamdesk": {
      "command": "python",
      "args": ["C:\\path\\to\\server.py"],
      "env": {
        "TEAMDESK_API_TOKEN": "your_token_here",
        "TEAMDESK_DATABASE_ID": "your_database_id"
      }
    }
  }
}

备选方案： .env 文件

您可以创建一个 .env 文件旁边 server.py:

cp .env.example .env
# Edit .env with your credentials

工具

筛选器示例

[Status] = 'Ativo'
[Amount] > 1000
Contains([Name], 'Solar')
[Date] >= ToDate('2026-01-01')

排序语法

Column          -- ascending (default)
Column//DESC    -- descending

TeamDesk API测验

这些是此服务器正确处理的未记录行为：

故障排除

MCP未出现在Claude Desktop中

• 确保您完全重新启动了Claude Desktop（检查系统托盘）
• 验证 python 在您的路径中： python --version
• 检查配置JSON语法（无尾随逗号）

反应缓慢

• TeamDesk服务器在美国工作时间（15:00–18:00 UTC）可能会变慢
• 服务器在超时时自动重试（最多2次）
• 检查日志：克劳德桌面>Ctrl+Shift+I>控制台>过滤器 [TeamDesk MCP]

代币问题

• 在以下位置生成新令牌：TeamDesk>设置>集成>REST API>令牌
• 令牌应该是一个32个字符的十六进制字符串
• 两者 TEAMDESK_API_TOKEN 和 TEAMDESK_TOKEN （遗产）被接受

远程部署

这 deploy/ 文件夹包含 server_sse.py --一个多用户远程MCP服务器，设计用于部署在Nginx/TLS后面的VPS上。它支持：

• OAuth 2.0 具有自动批准功能（PKCE S256）——claude.ai自定义连接器要求
• 可流式传输的HTTP 传输（MCP SDK 1.26.0+）——claude.ai使用的协议
• 上海证券交易所 传输——用于通过URL进行Claude Desktop本地配置
• 多用户身份验证 通过存储在TeamDesk表中的API密钥
• 速率限制 和 响应缓存
• 每用户令牌 -每个用户的API密钥映射到他们自己的TeamDesk令牌

运作原理

1. 管理员在中创建记录 Acesso 桌子（TeamDesk）上有：

- Chave_MCP：用户的唯一密钥（例如。， john_company_2026) - Token：用户的TeamDesk API令牌 - Ativo_MCP: Sim （启用访问）

1. 每个用户都有一个个人端点： https://your-server.com/m/{chave}/sse

1. 服务器验证密钥，检索用户的令牌，并使用该令牌将所有MCP工具调用代理到TeamDesk API。

OAuth 2.0端点

claude.ai需要这些OAuth端点用于自定义连接器：

技术说明

• claude.ai使用 发布 （流式HTTP），而不是GET（SSE）——服务器处理这两者
• 服务器注入 Accept: application/json, text/event-stream 如果缺少标头（claude.ai有时会省略它，导致MCP SDK中出现406）
• 会议是 有状态的 (stateless=False)--持久性所需 Mcp-Session-Id
• 通过环境变量进行配置（请参见 deploy/docker-compose.yml)

Docker部署

cd deploy
cp .env.example .env
# Edit .env with your TEAMDESK_DATABASE_ID, TEAMDESK_MASTER_TOKEN, MCP_PUBLIC_URL
docker compose up -d

密钥发现：网络=桌面=移动

当用户在上配置自定义连接器时 claude.ai （网络），它会自动在 克劳德桌面版 和 克劳德移动 --不需要单独的配置。连接器链接到用户的Anthropic 账户，而不是特定的应用程序。

这意味着： 网络上的一个设置涵盖了所有平台。

安全

• 令牌是从环境变量中读取的，从不进行硬编码
• 通过转义单引号防止过滤器注入
• 表名采用URL编码，以保留重音字符
• 根据TeamDesk表验证API密钥（非硬编码）
• OAuth自动批准使用PKCE S256进行安全保护
• 速率限制可防止滥用（可配置每分钟限制）
• 看 安全.md 负责披露

许可证

麻省理工学院