An MCP (Model Context Protocol) server that enables Claude to book, cancel, and query Focusmate accountability sessions.

• Book sessions - Schedule Focusmate sessions for specific dates and times
• Cancel sessions - Cancel existing sessions by ID
• List sessions - Query upcoming and past sessions within a date range
• Interactive authentication - Secure browser-based login with cookie persistence

# Clone the repository
git clone https://github.com/goodgravy/focusmate-mcp.git
cd focusmate-mcp

# Install dependencies
npm install

# Build
npm run build

# Install Playwright browsers
npx playwright install chromium

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "focusmate": {
      "command": "node",
      "args": ["/path/to/focusmate-mcp/build/index.js"]
    }
  }
}

Replace /path/to/focusmate-mcp with the actual path to your installation.

To use the list_sessions tool, you need a Focusmate API key:

1. Go to Focusmate Settings
2. Scroll to the API section and generate an API key
3. Create the config file:

mkdir -p ~/.focusmate-mcp
echo '{"apiKey": "your-api-key-here"}' > ~/.focusmate-mcp/config.json
chmod 600 ~/.focusmate-mcp/config.json

Before booking or canceling sessions, authenticate with Focusmate:

Use the focusmate_auth tool to log in

This opens a browser window where you can log in to Focusmate. Once logged in, your session is saved automatically.

Open a browser window to log into Focusmate. Cookies are saved for future use.

Parameters:

• force (boolean, optional): Force re-authentication even if valid cookies exist

Example:

Authenticate with Focusmate

Book a Focusmate accountability session.

Parameters:

• startTime (string, required): ISO 8601 datetime for session start
• duration (string, optional): Session duration - "25", "50", or "75" minutes (default: "50")

Example:

Book a 50-minute Focusmate session for tomorrow at 2pm

Note: Sessions must start on 15-minute boundaries (e.g., 14:00, 14:15, 14:30, 14:45).

Cancel an existing Focusmate session.

Parameters:

• sessionId (string, required): The ID of the session to cancel

Example:

Cancel my Focusmate session with ID abc123

List Focusmate sessions within a date range.

Parameters:

• startDate (string, required): Start of date range (ISO 8601)
• endDate (string, optional): End of date range (defaults to 7 days from startDate)

Example:

Show my Focusmate sessions for this week

• Cookies: ~/.focusmate-mcp/cookies.json
• Config: ~/.focusmate-mcp/config.json
• Screenshots: ~/.focusmate-mcp/screenshots/

# Run in development mode
npm run dev

# Run tests
npm test

# Type check
npm run lint

Run focusmate_auth to log in again. Focusmate sessions typically expire after several hours of inactivity.

Check for screenshots in ~/.focusmate-mcp/screenshots/. The automation captures a screenshot when it fails, which can help diagnose UI changes or unexpected states.

The list_sessions tool uses Focusmate's official API, which requires an API key. Book and cancel operations use browser automation and only need cookies from focusmate_auth.

Ensure Playwright browsers are installed:

npx playwright install chromium

• Read-only API: Focusmate's official API only supports reading data. Booking and cancellation use browser automation, which may break if Focusmate changes their UI.
• Rate limiting: The API has a limit of 100 requests per minute. Browser automation is naturally slower and shouldn't hit limits.
• Session duration: Only 25, 50, and 75-minute sessions are supported (Focusmate's standard options).

MIT