Boostu Teamleader MCP Server

🔗 BoostU Teamleader MCP

The open-source Teamleader Focus MCP server. Manage your CRM from Claude and other AI assistants, in plain language. 🤖

---

💡 What is this?

boostu-teamleader-mcp is a Model Context Protocol server that exposes the Teamleader Focus API to AI assistants — including Claude Desktop, Claude Code, Cursor, and Windsurf. It provides over 100 tools spanning the full Teamleader Focus surface: CRM (contacts, companies, deals), sales documents (quotations, invoices, credit notes), product catalog, subscriptions, projects, time tracking, customer-service tickets, and more. Point your AI at it and manage your entire CRM through natural language.

Prefer not to self-host?

Use the managed, always-on edition at teamleader-mcp.boostu.be — no OAuth setup, magic-link login, and a one-click connector for Claude. Free during the preview, paid plans after.

This repository is the open-source MCP server itself: run it locally with your own Teamleader integration. The hosted edition adds multi-tenant authentication, a dashboard, usage insights, and managed token handling on top of the same server.

---

🔌 How it works

flowchart LR
    U["🧑 You"] -->|"plain language"| C["🤖 Claude / AI assistant"]
    C <-->|"MCP · stdio"| S["🔗 boostu-teamleader-mcp"]
    S <-->|"OAuth2 REST"| T["📇 Teamleader Focus API"]

You ask Claude in plain language. Claude calls this MCP server, which authenticates to Teamleader Focus over OAuth2 and runs the matching API call. Your data stays in Teamleader; this server only brokers the calls.

Use the outline button at the top-right of this file to jump to any section.

---

✨ Highlights

• 👥 Full CRM: create and update contacts, companies, and deals across all pipelines
• 🧾 Quotations and invoicing: create quotations on deals, book invoices into accounting, send by email, and register payments
• 📦 Product catalog: browse products, categories, price lists, and units of measure
• 🔁 Subscriptions: create, update, and deactivate recurring subscriptions
• 📊 Projects and time tracking: manage projects, milestones, log time entries, and start/stop live timers
• 🎫 Customer-service tickets: open tickets, post replies, and update statuses
• 🔎 Reference-data lookups: resolve deal phases, pipelines, tax rates, payment terms, lost reasons, and more
• 🔐 OAuth2 with automatic refresh-token rotation: tokens are refreshed transparently; rotated tokens are persisted to a configurable file
• 🧩 Selectable tool groups: load only the groups you need via TEAMLEADER_TOOLS to keep your assistant's context lean

---

🚀 Quick Start

Run without installing

npx boostu-teamleader-mcp

Global install

npm i -g boostu-teamleader-mcp
boostu-teamleader-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json or ~/.claude/mcp.json:

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

---

🔐 Authentication

You need three env vars: TEAMLEADER_CLIENT_ID, TEAMLEADER_CLIENT_SECRET, and TEAMLEADER_REFRESH_TOKEN. Obtain them by registering an integration in the Teamleader Marketplace / Developer portal and completing the OAuth2 authorization flow.

Teamleader rotates the refresh token on every API call. Set TEAMLEADER_TOKEN_STORE to a writable file path so the server can persist the latest token between restarts — without it the token in your config will go stale after the first restart.

For the full step-by-step walkthrough (authorize URL, code exchange, helper scripts) see docs/AUTHENTICATION.md.

---

⚙️ Configuration

Environment variables

Selective tool groups

Use TEAMLEADER_TOOLS to limit which tool groups are registered. This is useful when you want to keep the assistant's tool list small or restrict access to certain areas of Teamleader.

TEAMLEADER_TOOLS=deals,quotations,products

Full list of group keys:

---

🧰 Available Tools

Contacts

Companies

Deals

Tasks

Events

Invoices

Quotations

Products

Reference Data

Organisation

Custom Fields

Credit Notes

Subscriptions

Projects

Time Tracking

Activities (Calls & Meetings)

Tickets

Tags

Notes

Files

Webhooks

---

💬 Example Prompts

Create a quotation for deal <id> with two line items: 5 hours of consulting at €150/h and a one-time setup fee of €500.

Book the draft invoice <id> into accounting and then send it to the customer.

Register a €1 200 payment against invoice <id> received today via bank transfer.

Log 2.5 hours on project <id> for user <user_id> with the note "API integration work".

Start a timer for me right now — I'm working on the BoostU onboarding project.

Open a support ticket for company <id>: subject "Login not working", priority high.

What deal phase IDs do we have in pipeline <id>? I need to move deal <id> to the "Proposal sent" phase.

List all products in the "Hosting" category and their prices.

Create a monthly subscription for company <id>: product <product_id>, quantity 1, starting next month.

Show me all open deals with their current phases and tell me which ones haven't moved in the last 30 days.

---

🐳 Docker

docker run --rm \
  -e TEAMLEADER_CLIENT_ID=your-client-id \
  -e TEAMLEADER_CLIENT_SECRET=your-client-secret \
  -e TEAMLEADER_REFRESH_TOKEN=your-refresh-token \
  -e TEAMLEADER_TOKEN_STORE=/data/teamleader-token \
  -v /var/run/teamleader:/data \
  ghcr.io/boostuagency/boostu-teamleader-mcp

---

🛠️ Development

# Clone and install
git clone https://github.com/boostuagency/boostu-teamleader-mcp.git
cd boostu-teamleader-mcp
npm install

# Run in development mode (no build step required)
npm run dev

# Build
npm run build

# Run tests
npm test

# Type-check only
npm run typecheck

---

🏗️ Architecture

The core of the server is createServer in src/server.ts, which is transport-agnostic — it takes a TeamleaderClient and registers the enabled tool groups, returning a plain McpServer instance that the entry point (src/index.ts) wires to a StdioServerTransport. Tool logic lives in per-domain modules under src/tools/, each following a consistent try / respond / catch / respondError pattern using shared helpers in src/lib/. OAuth2 token acquisition and rotation are handled entirely in src/api/auth.ts, transparent to the rest of the codebase. A hosted, multi-tenant edition of this server is available at teamleader-mcp.boostu.be.

---

✅ Endpoint Verification

Most read endpoints (*.list, *.info) have been live-verified against the Teamleader Focus API. Several write and action endpoints (e.g. subscriptions.create, projects.create, files.upload) are implemented from the official documentation but have not been tested against a live account with the relevant module active. If an endpoint name is wrong, the call will fail with a clear HTTP error message rather than silently misbehaving. The full endpoint manifest and verification status are documented in docs/teamleader-endpoints.md.

---

🤝 Contributing

See CONTRIBUTING.md for development setup, commit conventions, and instructions on adding new tool groups.

---

🔒 Security

Report security vulnerabilities to nick@boostu.be — do not open a public issue. See SECURITY.md for the disclosure policy. Never commit .env files or .teamleader-token to version control; both are listed in .gitignore.

---

⚖️ Disclaimer

This is an independent, community-built integration. It is not affiliated with, endorsed by, or sponsored by Teamleader NV. "Teamleader" and "Teamleader Focus" are trademarks of Teamleader NV and are used here only to describe compatibility. You are responsible for your own use of the Teamleader API under Teamleader's terms.

---

📄 License

MIT License — Copyright (c) 2026 BoostU Agency. See NOTICE for upstream attribution.