AI导哈

数据库连接服务器

TeamDesk MCP Server是一个连接Claude及兼容客户端与TeamDesk数据库的协议服务器，支持CRUD操作、搜索和文档生成。

  • by Danielbluz
  • Python
  • 混合部署
  • 4 星标
  • 更新于
在 GitHub 查看 Danielbluz/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

工具

工具 说明
list_tables 列出数据库中的所有表
describe_table 获取表结构（列、类型、属性）
get_records 使用过滤器、排序和分页查询记录
get_record 按ID检索单个记录
select_view 从预配置的视图查询记录
create_record 创建新记录
update_record 按ID更新现有记录
delete_record 按ID删除记录
search_records 跨文本列的全文搜索（自动检测）
upsert_records 插入或更新记录（匹配列必须是唯一的）
gerar_documento 从TeamDesk文档模板生成DOCX

筛选器示例

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

排序语法

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

TeamDesk API测验

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

Quirk 详细信息
DELETE使用GET {table}/delete.json?id={id} 是GET请求
UPDATE使用POST Not PUT。正文必须包括 @row.id
正文必须是数组 所有写入操作都需要 [{...}]，不 {...}
上游匹配必须是唯一的 表设置中的匹配列必须标记为唯一，否则出现错误3106
文档终结点没有 .json 使用 /document?id=X，不 /document.json?id=X
排序用途 // Column//DESC，不 -Column 或 Column DESC
重音名称有效 Geração, Irradiação --必须进行URL编码，而不是剥离
无LIKE运算符 使用 Contains([field], 'value') 不区分大小写
日期文字使用 # [Date] >= #2026-01-01# 或 ToDate('2026-01-01')
按ID检索 使用 retrieve.json?id=X，不 {id}.json

故障排除

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 （启用访问）

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

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

OAuth 2.0端点

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

终点 目的
/.well-known/oauth-protected-resource RFC 9728——资源元数据
/.well-known/oauth-authorization-server RFC 8414——身份验证服务器元数据
/register RFC 7591——动态客户端注册
/authorize 授权端点（自动批准）
/token 令牌交换（PKCE S256验证）

技术说明

  • 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 负责披露

许可证

麻省理工学院

相关 MCP