Teamleader Focus MCP

A Model Context Protocol (MCP) server that wraps the Teamleader Focus CRM API. Gives AI assistants (Claude Code, Claude Desktop, Cursor, etc.) the ability to manage contacts, companies, deals, tasks, events, invoices, time tracking, and projects — including a smart task resolution workflow for automated time logging.

Inspired by globodai-group/mcp-teamleader. Rewritten and extended with full API coverage, time tracking, projects v2, and smart cache-first task resolution.

Features

• Contacts — List, get, create, update
• Companies — List, get, create
• Deals — List, get, create, update
• Tasks — List, create (legacy task API)
• Events — List, get, create calendar events
• Invoices — List, get, create draft invoices
• Time Tracking — List, add, update, delete, start/stop timers
• Projects v2 — List, get, create, update projects, groups (phases), and tasks
• Smart Resolution — Cache-first Company > Project > Group > Task navigation
• OAuth2 — Automatic token refresh with rotation support

Prerequisites

A Teamleader Focus account with API access:

1. Go to Developer Portal
2. Register an integration to get your Client ID and Client Secret
3. Complete the OAuth2 flow to obtain a Refresh Token (see QUICKSTART.md)

Quick Start

Option A — npx (recommended, no install needed)

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/.claude.json:

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "@tailormade/teamleader-focus-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your_client_id",
        "TEAMLEADER_CLIENT_SECRET": "your_client_secret",
        "TEAMLEADER_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Option B — Build from source

git clone https://github.com/tailormade-eu/Tailormade.TeamleaderFocusMcp.git
cd Tailormade.TeamleaderFocusMcp
npm install
npm run build

Add to your Claude config:

{
  "mcpServers": {
    "teamleader": {
      "command": "node",
      "args": ["C:\\ABSOLUTE\\PATH\\TO\\dist\\index.js"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your_client_id",
        "TEAMLEADER_CLIENT_SECRET": "your_client_secret",
        "TEAMLEADER_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Configuration

Environment Variables

Cache Files

Available Tools

Contacts

Companies

Deals

Tasks (standalone)

Events

Meetings

Invoices

Tickets

Time Tracking

Projects v2

Users

Departments

Files

Notes

Lookup Lists

Smart Resolution (Cache-first)

These tools implement the recommended workflow for time logging. They maintain a local cache to avoid repeated API calls.

Authentication

Recommended Workflow: Time Logging

Option A — Interactive (first use or unknown task)

1. teamleader_find_task(company_name="Acme", group_name="Sprint 12", task_name="Bug fix login")
   → resolves company > project > group > task, caches result

2. teamleader_log_time(company_name="Acme", task_name="Bug fix login", started_on="09:00", ended_on="11:30")
   → reads from cache, logs time entry, checks for duplicates

Option B — Load tree first (recommended for sessions with many log entries)

1. teamleader_load_tasks(company_name="Acme")
   → fetches full tree, writes ~/.teamleader-tasks-acme.yaml, shows summary

2. teamleader_load_tasks(company_name="Acme", visual=true)
   → shows numbered ASCII tree

   Company: Acme Corp
   === Project Alpha ===
     [Sprint 12]
       1. Bug fix login (to_do)
       2. Add unit tests (in_progress)

3. teamleader_load_tasks(company_name="Acme", task_selection=1)
   → caches task #1 for direct use

4. teamleader_log_time(company_name="Acme", task_name="Bug fix login", started_on="09:00", ended_on="11:30")
   → resolves from cache, logs time

Option C — Direct task_id (fastest, when ID is already known)

teamleader_log_time(company_name="Acme", task_id="abc-123", started_on="09:00", ended_on="11:30")

Smart Resolution: teamleader_find_task Parameters

Smart Resolution: teamleader_log_time Parameters

Deduplication Rules (teamleader_log_time)

teamleader_load_tasks Parameters

Cache TTL

Auto-prune: expired entries are removed on every cache write.

Teamleader API Quirks

These are critical for any future development or debugging.

projects-v2/projectLines.list

• project_id must be top-level in the request body — NOT inside filter
• project_group_id is NOT a server-side filter — must filter client-side on l.group?.id

projects-v2/tasks.list

• Filter by ids array works server-side
• Status is NOT a server-side filter — filter client-side on status field

projects-v2/tasks.create

• Use group_id (NOT project_group_id)
• Use tasks.create endpoint (NOT projectLines.create)

timeTracking.list

• Returns subject.type: "todo" — the ID differs from the nextgenTask ID
• Deduplication must match on start time (to second precision), not on subject ID

invoices.registerPayment

• Uses paid_at (NOT payment_date)
• Payment is a nested object: { payment: { amount: { amount, currency }, paid_at, payment_method_id } }

invoices.creditPartially

• Line item tax uses unit_price.tax: "excluding" (NOT a currency field)

tickets.list

• Customer filter uses relates_to: { type, id } (NOT customer_id)
• Status filter uses exclude.status_ids array (no direct status filter)

projects.close

• Requires closing_strategy: "mark_tasks_and_materials_as_done" or "none"

projects.delete

• Requires delete_strategy: "unlink_tasks_and_time_trackings" or "delete_tasks_and_time_trackings"

projects.assign / projects.addCustomer

• assign uses assignee: { type, id } object
• addCustomer / removeCustomer use customer: { type, id } object

projectGroups.update

• Uses start_date / end_date (NOT starts_on / due_on)

files.upload

• Two-step process: call files.upload to get a pre-signed URL, then POST binary directly to that URL (no auth needed for step 2)

General

• All API calls use POST with JSON body
• Base URL: https://api.focus.teamleader.eu
• Pagination uses page.number and page.size

File Structure

src/
  api/
    auth.ts         — OAuth2 token management (auto-rotate, persist to ~/.teamleader-tokens.json)
    client.ts       — HTTP client (all POST requests)
    cache.ts        — Cache types, TTL constants, CRUD functions, task tree operations
  tools/
    resolve.ts      — Smart tools: find_task, log_time, load_tasks, task_action, cache_stats, clear_cache
    contacts.ts     — Contact tools
    companies.ts    — Company tools
    deals.ts        — Deal tools
    tasks.ts        — Legacy task tools
    events.ts       — Event tools
    invoices.ts     — Invoice tools
    timetracking.ts — Time tracking + timers tools
    projects.ts     — Projects v2 tools
  index.ts          — MCP server entry point, tool registration
docs/
  api/              — Full Teamleader Focus API docs (187 pages, scraped from developer.focus.teamleader.eu)
  find-task-business-logic.md — Detailed business logic for smart resolution tools
tasks/              — CodingMachine task queue (planned tool additions)

Development

# Install
npm install

# Build (TypeScript → dist/)
npm run build

# Type check only
npm run typecheck

# Dev mode (watch)
npm run dev

# Test with MCP inspector
npx @modelcontextprotocol/inspector node dist/index.js

API Reference

• Teamleader Focus API docs: developer.focus.teamleader.eu
• Local scraped docs: docs/api/ (360 pages, updated 2026-03-05)
• Base URL: https://api.focus.teamleader.eu
• All endpoints use POST with JSON body
• Authentication: OAuth2 with automatic token refresh

Roadmap (CodingMachine tasks in tasks/)

License

MIT