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

• 112 tools covering the full Teamleader Focus API
• Contacts — Full CRUD + tag/untag + company link management
• Companies — Full CRUD + tag/untag
• Deals — Full CRUD + win/lose/move + pipelines/phases/sources management
• Tasks — Standalone tasks: full CRUD + complete/reopen/schedule
• Events — List, get, create, update, cancel
• Meetings — Full CRUD + complete + reports
• Invoices — Full lifecycle: draft → book → send → payment → credit
• Tickets — Full CRUD + messages + reply/internal
• Time Tracking — List, add, update, delete + start/stop/resume timers + timesheet
• Projects v2 — Full CRUD + groups + tasks + relationships + lifecycle
• Subscriptions — Full CRUD + deactivate
• Quotations — Full CRUD + accept/send/download
• Materials — Full CRUD + assign/unassign/duplicate
• Files — List, get, download, delete, upload
• Notes — List, create, update
• Calls — List, get, add, update, complete
• Smart Resolution — Cache-first Company > Project > Group > Task navigation + time logging
• OAuth2 — Browser-based login flow + automatic token refresh with rotation
• Resilience — Automatic retry on rate limits (429, exponential backoff) and mid-flight token expiry (401 force-refresh + 1 retry)
• Output cap — Responses exceeding 50 KB are written to a temp file; the tool returns an excerpt + path

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

Subscriptions

Quotations

Credit Notes

Materials

Calls

Orders

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 CRUD + tag/link
    companies.ts      — Company CRUD + tag
    deals.ts          — Deal CRUD + pipelines/phases/sources
    tasks.ts          — Standalone tasks
    events.ts         — Events
    meetings.ts       — Meetings + reports
    invoices.ts       — Invoices + payment + credit
    timetracking.ts   — Time tracking + timers + timesheet
    projects.ts       — Projects v2 + groups + lines + project tasks
    tickets.ts        — Tickets + messages
    subscriptions.ts  — Subscriptions
    quotations.ts     — Quotations
    creditnotes.ts    — Credit notes
    materials.ts      — Materials
    calls.ts          — CRM calls
    orders.ts         — Orders
    files.ts          — Files
    notes.ts          — Notes
    users.ts          — Users
    departments.ts    — Departments
    lookups.ts        — All reference data lists
    login.ts          — OAuth login flow
  index.ts            — MCP server entry point, tool registration
docs/
  api/                — Full Teamleader Focus API docs (360 pages, scraped 2026-03-05)
  BusinessLogica/     — Business logic docs per domain

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

References

• Teamleader Focus API — OAuth2 REST API (all POST, JSON body)
• Model Context Protocol — MCP specification
• globodai-group/mcp-teamleader — Original inspiration
• Local scraped API docs: docs/api/ (360 pages, updated 2026-03-05)

API Reference

• Base URL: https://api.focus.teamleader.eu
• All endpoints use POST with JSON body
• Authentication: OAuth2 with automatic token refresh

License

MIT