🔗 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_TOOLSto 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.
Move the valid-until date of quotation <id> to the end of next month, then email the customer a reminder in Dutch with the signing link.
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 [email protected] — 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.