Teamsnapmcp

🚀 TeamSnap MCP 服务器

这是一个 模型上下文协议（MCP）服务器，它能将 Claude 与你的 TeamSnap 账户连接起来。你可以直接从 Claude 桌面端或命令行界面访问你的团队、花名册、活动和可用性数据。

🚀 快速开始

1. 获取 TeamSnap OAuth 凭证

1. 访问 TeamSnap 开发者门户。
2. 创建一个新的应用程序。
3. 设置重定向 URI（请参阅下面的部署选项）。
4. 记录下你的 客户端 ID 和 客户端密钥。

2. 选择部署方式

选项 A：本地 MCP 服务器

此方式最适合开发。OAuth 回调需要一个隧道（例如 Cloudflare）。

git clone https://github.com/mrelph/TeamSnapMCP.git
cd TeamSnapMCP
cp .env.example .env   # 添加你的凭证
npm install
npm run build

将以下内容添加到 Claude 桌面端配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "teamsnap": {
      "command": "node",
      "args": ["/path/to/TeamSnapMCP/dist/index.js"],
      "env": {
        "TEAMSNAP_CLIENT_ID": "your-client-id",
        "TEAMSNAP_CLIENT_SECRET": "your-client-secret",
        "TEAMSNAP_REDIRECT_URI": "https://your-tunnel-url/callback"
      }
    }
  }
}

💡 提示：使用 cloudflared tunnel --url http://localhost:8374 创建一个 HTTPS 回调 URL。

选项 B：npx（连接到 AWS 部署）

如果 AWS 后端已经部署，这是最简单的选项，无需本地克隆。

{
  "mcpServers": {
    "teamsnap": {
      "command": "npx",
      "args": ["-y", "teamsnap-mcp"],
      "env": {
        "TEAMSNAP_MCP_ENDPOINT": "https://your-api-id.execute-api.us-east-1.amazonaws.com/mcp"
      }
    }
  }
}

选项 C：AWS 无服务器部署

部署到 AWS Lambda 以获得永久的 HTTPS 回调 URL，无需隧道。

cd aws
npm install

设置环境变量：

export AWS_ACCESS_KEY_ID=your-aws-key
export AWS_SECRET_ACCESS_KEY=your-aws-secret
export AWS_REGION=us-east-1
export TEAMSNAP_CLIENT_ID=your-client-id
export TEAMSNAP_CLIENT_SECRET=your-client-secret

部署：

node scripts/deploy.cjs

这将创建：

• API 网关 — 永久的 HTTPS 端点
• Lambda — MCP 服务器（Node.js 20，256MB，30 秒超时）
• DynamoDB — 带有 TTL 自动清理功能的令牌存储

然后配置 Claude 桌面端使用 包装器：

{
  "mcpServers": {
    "teamsnap": {
      "command": "node",
      "args": ["/path/to/TeamSnapMCP/dist/wrapper.js"],
      "env": {
        "TEAMSNAP_MCP_ENDPOINT": "https://your-api-id.execute-api.us-east-1.amazonaws.com/mcp"
      }
    }
  }
}

3. 进行身份验证

告诉 Claude："连接到 TeamSnap" 一个浏览器窗口将打开以进行 OAuth 登录。授权后，你就完成了连接。

✨ 主要特性

• 团队管理 — 列出并查看你所有的 TeamSnap 团队。
• 花名册管理 — 获取球员和教练的信息。
• 活动管理 — 查看比赛、训练和其他活动，并可按日期过滤。
• 可用性检查 — 检查哪些人可以参加活动，正确处理所有 RSVP 状态，包括数字状态代码。
• 安全可靠 — 使用 OAuth 2.0 进行身份验证，本地存储或 DynamoDB 使用 AES - 256 - GCM 加密。
• 灵活部署 — 可以在本地运行，通过 npx 运行，或部署到 AWS Lambda。

📦 安装指南

前提条件

• Node.js >= 18
• 一个 TeamSnap 开发者 OAuth 应用程序（客户端 ID + 密钥）

💻 使用示例

示例提示

• "我在 TeamSnap 中有哪些团队？"
• "给我看看 Jr Kraken 队的花名册。"
• "我们这个月有哪些比赛安排？"
• "周六的比赛谁有空参加？"
• "谁拒绝参加周六的比赛？"

📚 详细文档

可用工具

可用性状态代码

teamsnap_get_availability 工具根据 API 返回的 TeamSnap status_code 字段将成员分为四类：

⚠️ 重要提示：JavaScript 中，“拒绝”的数字代码 0 是一个假值。服务器在读取 status_code 时使用空值合并运算符 (??) 而非逻辑或运算符 (||)，以确保数字 0 能正确归类为“拒绝”，而不是默认归为“未回复”。

🔧 技术细节

架构

本地部署:

  Claude 桌面端 <--stdio--> MCP 服务器 (Node.js)
                                   |
                              TeamSnap API
                                   |
                         localhost:8374 (OAuth 回调)


AWS 部署:

  Claude 桌面端 <--stdio--> 包装器 --HTTPS--> API 网关
                                                     |
                                                  Lambda
                                                  |     |
                                            DynamoDB   TeamSnap API

环境变量

安全性

• 加密 — 本地令牌使用 AES - 256 - GCM 加密（scrypt 密钥派生）。
• 只读权限 — 仅从 TeamSnap 请求 read 范围。
• 无硬编码凭证 — 所有机密信息从环境变量加载。
• CSRF 保护 — 验证 OAuth 状态参数。
• 自动清理 — DynamoDB TTL 在 10 分钟后移除过期的待认证信息。
• 文件权限 — 本地凭证以 0600（仅所有者可访问）权限保存。

开发

npm install       # 安装依赖
npm run build     # 编译 TypeScript
npm run dev       # 监听模式
node dist/index.js      # 运行本地服务器
node dist/wrapper.js    # 运行 AWS 包装器

AWS 部署

cd aws
npm install
npm run build           # 使用 esbuild 打包
node scripts/deploy.cjs # 部署到 AWS

📄 许可证

本项目采用 MIT 许可证。