Btrainr MCP Server

An implementation of the Model Context Protocol (MCP) for the Btrainr coaching platform. This server exposes Btrainr functionalities as tools that can be used by LLMs (Claude, Cursor, OpenAI, etc.) to manage clients, leads, check-ins, and communications.

Features

• MCP Standard Compliant: Implements the Model Context Protocol over standard I/O (Stdio) by default, with optional SSE support.
• Type-Safe Tools: All tools are defined with Zod schemas for robust validation.
• Built-in Safety Gates: Write operations (create_lead, update_lead, send_message, add_client_tag, create_client_note) require explicit confirmation (confirm: true) and support dry runs (dry_run: true).
• Client & Lead Management: Query and update clients, check-ins, notes, and leads directly from your AI assistant.
• Interactive Chat CLI: Built-in CLI chat client to test tools interactively using OpenAI models.

Quick Start (with npx)

You can run the Btrainr MCP server directly without cloning or manually building:

npx -y btrainr-mcp

Claude Desktop Configuration

Add the following to your claude_desktop_config.json (located at %APPDATA%\Claude\claude_desktop_config.json on Windows, or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "btrainr": {
      "command": "npx",
      "args": ["-y", "btrainr-mcp"],
      "env": {
        "BTRAINR_API_KEY": "your_btrainr_api_key_here",
        "BTRAINR_API_URL": "https://btrainr.com/api"
      }
    }
  }
}

Cursor Configuration

Add to your .cursor/mcp.json or Cursor MCP settings:

{
  "mcpServers": {
    "btrainr": {
      "command": "npx",
      "args": ["-y", "btrainr-mcp"],
      "env": {
        "BTRAINR_API_KEY": "your_btrainr_api_key_here",
        "BTRAINR_API_URL": "https://btrainr.com/api"
      }
    }
  }
}

Architecture

Local Installation & Development

1. Clone & Install Dependencies

git clone https://gitlab.com/Bcoder24/btrainr-mcp.git
cd btrainr-mcp
npm install

2. Configure Environment

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

BTRAINR_API_KEY=your_btrainr_api_key_here
BTRAINR_API_URL=https://btrainr.com/api
PORT=3000
OPENAI_API_KEY=sk-your-openai-api-key-here # Only needed for scripts/chat.ts

3. Build

npm run build

4. Run MCP Server

• Stdio Mode (Default):

  npm start

• SSE Mode (HTTP):

  node dist/server.js --sse --port 3000

5. Interactive Chat CLI

Test your MCP tools using an interactive conversational agent powered by OpenAI:

npm run chat

Available Tools

Client Tools

• list_clients: Lists clients in the workspace. Supports filtering by status (active, inactive, pending) and pagination (limit, skip).
• get_client_profile: Retrieves detailed profile information for a client by ID.
• get_client_checkins: Fetches recent check-in history for a client.
• add_client_tag: Adds a tag (e.g. 'vip', 'injury') to a client. Requires confirm: true.
• send_message: Sends a message to a client. Requires confirm: true.
• create_client_note: Creates a private note for a client. Requires confirm: true.

Lead Tools

• list_leads: Lists leads in the current workspace with pagination and status filters.
• get_lead: Gets detailed profile for a specific lead by ID.
• create_lead: Creates a new lead with contact information (name, email, phone). Requires confirm: true.
• update_lead: Updates lead details (name, email, phone). Requires confirm: true.

Safety Gates on Write Actions

Every modifying action inherits the safety schema:

• confirm (boolean): Must be true to execute the mutation. If omitted or false, the operation is blocked.
• dry_run (boolean, optional): Simulates the execution without committing changes.
• reason (string, optional): Audit rationale recorded in service logs.

Publishing to npm

To publish this package to npm:

1. Log in to your npm account:

   npm login

2. Verify packaging contents:

   npm pack --dry-run

3. Publish:

   npm publish --access public

License

ISC © Btrainr