TeamSnap MCP Server

A Model Context Protocol (MCP) server that connects Claude to your TeamSnap account. Read and manage teams, rosters, events, availability, volunteer sign-ups, and team communications directly from Claude Desktop or CLI.

Features

• 21 read tools — teams, rosters, events, availability, locations, contacts, announcements, assignments, opponents, standings, stats, forums, calendars, and custom fields
• 8 write tools — set RSVPs, create/update/cancel events, create and assign tracked items (snacks, volunteers, carpools), send team messages, and send broadcast email/push announcements
• Safety rails on every write — preview: true by default returns the payload without calling TeamSnap; destructive writes additionally require confirm: true; POST tools support an optional idempotency_key. See Write Tools & Safety.
• Localized event times — events always returned in their own timezone; optional viewer-timezone field for travel
• Secure — OAuth 2.0 with AES-256-GCM encrypted local storage or DynamoDB
• Flexible Deployment — Run locally, via npx, or on AWS Lambda

Prerequisites

• Node.js >= 18
• A TeamSnap Developer OAuth application (Client ID + Secret)

Quick Start

1. Get TeamSnap OAuth Credentials

1. Go to TeamSnap Developer Portal
2. Create a new application
3. Set the redirect URI (see deployment options below)
4. Note your Client ID and Client Secret

2. Choose Your Deployment

Option A: Local MCP Server

Best for development. Requires a tunnel (e.g., Cloudflare) for the OAuth callback.

git clone https://github.com/mrelph/TeamSnapMCP.git
cd TeamSnapMCP
cp .env.example .env   # Add your credentials
npm install
npm run build

Add to Claude Desktop config (~/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"
      }
    }
  }
}

Tip: Use cloudflared tunnel --url http://localhost:8374 to create an HTTPS callback URL.

Option B: npx (Connects to AWS Deployment)

Easiest option if the AWS backend is already deployed. No local clone needed.

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

Option C: AWS Serverless

Deploy to AWS Lambda for a permanent HTTPS callback URL — no tunnels needed.

cd aws
npm install

Set environment variables:

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

Deploy:

node scripts/deploy.cjs

This creates:

• API Gateway — Permanent HTTPS endpoint
• Lambda — MCP server (Node.js 20, 256MB, 30s timeout)
• DynamoDB — Token storage with TTL auto-cleanup

Then configure Claude Desktop to use the wrapper:

{
  "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. Authenticate

Tell Claude: “Connect to TeamSnap”

A browser window will open for OAuth login. Once you authorize, you’re connected.

Available Tools

Availability Status Codes

The teamsnap_get_availability tool groups members into four categories based on the TeamSnap status_code field returned by the API:

Note: The numeric code 0 for “declined” is a falsy value in JavaScript. The server uses nullish coalescing (??) rather than the logical OR (||) operator when reading status_code to ensure that a numeric 0 is correctly categorized as “no” rather than silently falling through to “no response”.

Write Tools & Safety

Phase 2 added 8 write tools that can modify TeamSnap data. They follow consistent safety rails:

• preview: true by default. Every write tool returns the payload it would send without actually calling TeamSnap, so you can inspect first. Pass preview: false to commit.
• confirm: true for destructive actions. teamsnap_send_announcement always requires it; teamsnap_update_event requires it only when the patch sets is_canceled: true.
• idempotency_key for POST tools. Optional 60-second in-memory dedup cache keyed on the value you supply. Best-effort on Lambda (short function lifetime).
• Re-authentication. If you authenticated before Phase 2, your existing token has read scope only. Your first write will return reauthentication_required — just run teamsnap_auth again to get a read write token. Reads continue to work throughout.

Example: preview → commit flow

You: "RSVP Mark as 'yes' for event 12345"
Claude (calls teamsnap_set_availability with defaults):
  { preview: true, would_patch: "availability 987", with: { status: "yes", status_code: 1, notes: null } }
You: "Looks right, do it"
Claude (calls teamsnap_set_availability with preview: false):
  { status: "yes", event_id: 12345, member_id: 67890, notes: null }

Example Prompts

Reading:

• “What teams do I have in TeamSnap?”
• “Show me the roster for the Jr Kraken”
• “What games do we have scheduled this month?”
• “Who’s available for Saturday’s game?”
• “Who has declined Saturday’s game?”

Writing (preview first, commit second):

• “Preview setting my RSVP to yes for Saturday’s game” → inspect the payload → “Looks right, do it”
• “Create a snack sign-up called ‘Post-game snacks’ for next week’s event”
• “Post a team message saying ‘Uniforms this Saturday are white’”
• “Draft an announcement to the team about Sunday’s rain-out — don’t send it until I confirm”

Architecture

Local Deployment:

  Claude Desktop  MCP Server (Node.js)
                                   |
                              TeamSnap API
                                   |
                         localhost:8374 (OAuth callback)

AWS Deployment:

  Claude Desktop  Wrapper --HTTPS--> API Gateway
                                                     |
                                                  Lambda
                                                  |     |
                                            DynamoDB   TeamSnap API

Environment Variables

Security

• Encryption — Local tokens encrypted with AES-256-GCM (scrypt key derivation)
• OAuth scope — read write scope requested from TeamSnap; writes are gated behind preview/confirm (see Write Tools & Safety)
• No hardcoded credentials — All secrets loaded from environment variables
• CSRF protection — OAuth state parameter validation
• Auto-cleanup — DynamoDB TTL removes stale pending auth after 10 minutes
• File permissions — Local credentials saved with 0600 (owner-only)

Development

npm install       # Install dependencies
npm run build     # Compile TypeScript
npm run dev       # Watch mode
node dist/index.js      # Run local server
node dist/wrapper.js    # Run AWS wrapper

AWS deployment

cd aws
npm install
npm run build           # Bundle with esbuild
node scripts/deploy.cjs # Deploy to AWS

License

MIT