{
  "markdown": "# 🔗 BoostU Teamleader MCP\n\n### The open-source Teamleader Focus MCP server. Manage your CRM from Claude and other AI assistants, in plain language. 🤖\n\n[![CI](https://github.com/boostuagency/boostu-teamleader-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/boostuagency/boostu-teamleader-mcp/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/boostu-teamleader-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/boostu-teamleader-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/boostu-teamleader-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/boostu-teamleader-mcp)\n[![node](https://img.shields.io/node/v/boostu-teamleader-mcp?logo=node.js&color=5FA04E)](https://nodejs.org)\n[![Model Context Protocol](https://img.shields.io/badge/Model_Context_Protocol-server-6C5CE7)](https://modelcontextprotocol.io)\n[![tools](https://img.shields.io/badge/tools-100%2B-2ea44f)](https://www.npmjs.com/package/boostu-teamleader-mcp)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)\n[![Made by BoostU](https://img.shields.io/badge/made_by-BoostU-000)](https://boostu.be)\n\n---\n\n## 💡 What is this?\n\n`boostu-teamleader-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) 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.\n\n> ### Prefer not to self-host?\n> Use the managed, always-on edition at **[teamleader-mcp.boostu.be](https://teamleader-mcp.boostu.be)** — no OAuth setup, magic-link login, and a one-click connector for Claude. Free during the preview, paid plans after.\n>\n> 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.\n\n| | Self-host (this repo) | Managed ([boostu.be](https://teamleader-mcp.boostu.be)) |\n|---|---|---|\n| **Price** | Free, MIT-licensed | Free preview, then paid |\n| **Setup** | Create your own Teamleader integration, run via `npx` | Copy one connector URL into Claude |\n| **Tokens** | You manage `.env` and the refresh token | Encrypted and rotated for you |\n| **Best for** | Developers and self-hosters | Non-technical teams\n\n---\n\n## 🔌 How it works\n\n```mermaid\nflowchart LR\n    U[\"🧑 You\"] -->|\"plain language\"| C[\"🤖 Claude / AI assistant\"]\n    C <-->|\"MCP · stdio\"| S[\"🔗 boostu-teamleader-mcp\"]\n    S <-->|\"OAuth2 REST\"| T[\"📇 Teamleader Focus API\"]\n```\n\nYou 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.\n\n> Use the outline button at the top-right of this file to jump to any section.\n\n---\n\n## ✨ Highlights\n\n- 👥 **Full CRM**: create and update contacts, companies, and deals across all pipelines\n- 🧾 **Quotations and invoicing**: create quotations on deals, book invoices into accounting, send by email, and register payments\n- 📦 **Product catalog**: browse products, categories, price lists, and units of measure\n- 🔁 **Subscriptions**: create, update, and deactivate recurring subscriptions\n- 📊 **Projects and time tracking**: manage projects, milestones, log time entries, and start/stop live timers\n- 🎫 **Customer-service tickets**: open tickets, post replies, and update statuses\n- 🔎 **Reference-data lookups**: resolve deal phases, pipelines, tax rates, payment terms, lost reasons, and more\n- 🔐 **OAuth2 with automatic refresh-token rotation**: tokens are refreshed transparently; rotated tokens are persisted to a configurable file\n- 🧩 **Selectable tool groups**: load only the groups you need via `TEAMLEADER_TOOLS` to keep your assistant's context lean\n\n---\n\n## 🚀 Quick Start\n\n### Run without installing\n\n```bash\nnpx boostu-teamleader-mcp\n```\n\n### Global install\n\n```bash\nnpm i -g boostu-teamleader-mcp\nboostu-teamleader-mcp\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"teamleader\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"boostu-teamleader-mcp\"],\n      \"env\": {\n        \"TEAMLEADER_CLIENT_ID\": \"your-client-id\",\n        \"TEAMLEADER_CLIENT_SECRET\": \"your-client-secret\",\n        \"TEAMLEADER_REFRESH_TOKEN\": \"your-refresh-token\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdd to your project's `.mcp.json` or `~/.claude/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"teamleader\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"boostu-teamleader-mcp\"],\n      \"env\": {\n        \"TEAMLEADER_CLIENT_ID\": \"your-client-id\",\n        \"TEAMLEADER_CLIENT_SECRET\": \"your-client-secret\",\n        \"TEAMLEADER_REFRESH_TOKEN\": \"your-refresh-token\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project root (or the global `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"teamleader\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"boostu-teamleader-mcp\"],\n      \"env\": {\n        \"TEAMLEADER_CLIENT_ID\": \"your-client-id\",\n        \"TEAMLEADER_CLIENT_SECRET\": \"your-client-secret\",\n        \"TEAMLEADER_REFRESH_TOKEN\": \"your-refresh-token\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"teamleader\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"boostu-teamleader-mcp\"],\n      \"env\": {\n        \"TEAMLEADER_CLIENT_ID\": \"your-client-id\",\n        \"TEAMLEADER_CLIENT_SECRET\": \"your-client-secret\",\n        \"TEAMLEADER_REFRESH_TOKEN\": \"your-refresh-token\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 🔐 Authentication\n\nYou 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](https://marketplace.focus.teamleader.eu) and completing the OAuth2 authorization flow.\n\nTeamleader **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.\n\nFor the full step-by-step walkthrough (authorize URL, code exchange, helper scripts) see [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md).\n\n---\n\n## ⚙️ Configuration\n\n### Environment variables\n\n| Name | Required | Description |\n|------|----------|-------------|\n| `TEAMLEADER_CLIENT_ID` | Yes | OAuth2 client ID from your Teamleader integration |\n| `TEAMLEADER_CLIENT_SECRET` | Yes | OAuth2 client secret from your Teamleader integration |\n| `TEAMLEADER_REFRESH_TOKEN` | Yes | Initial refresh token obtained from the OAuth2 authorization flow |\n| `TEAMLEADER_TOKEN_STORE` | No | Path to a writable file where the server persists the rotated refresh token (e.g. `/var/run/teamleader-token`). Strongly recommended in production. |\n| `TEAMLEADER_TOOLS` | No | Comma-separated list of tool group keys to enable. When unset, all 21 groups are loaded. |\n\n### Selective tool groups\n\nUse `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.\n\n```bash\nTEAMLEADER_TOOLS=deals,quotations,products\n```\n\nFull list of group keys:\n\n| Key | What it covers |\n|-----|---------------|\n| `contacts` | Contacts CRUD |\n| `companies` | Companies CRUD |\n| `deals` | Deals / opportunities |\n| `tasks` | Tasks |\n| `events` | Calendar events |\n| `invoices` | Invoices (create, book, send, pay, download) |\n| `quotations` | Quotations (create, update, send, accept) |\n| `products` | Product catalog and price lists |\n| `reference` | Deal phases, tax rates, payment terms, etc. |\n| `org` | Users, teams, departments |\n| `customFields` | Custom field definitions |\n| `creditNotes` | Credit notes |\n| `subscriptions` | Recurring subscriptions |\n| `projects` | Projects and milestones |\n| `timeTracking` | Time log entries and live timers |\n| `activities` | Calls and meetings |\n| `tickets` | Support tickets |\n| `tags` | Add/remove tags on contacts and companies |\n| `notes` | Notes on any subject |\n| `files` | File list, download, upload |\n| `webhooks` | Webhook registration |\n\n---\n\n## 🧰 Available Tools\n\n### Contacts\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_list_contacts` | List contacts from Teamleader Focus with optional filtering and pagination |\n| `teamleader_get_contact` | Get detailed information about a specific contact |\n| `teamleader_create_contact` | Create a new contact in Teamleader Focus |\n| `teamleader_update_contact` | Update an existing contact in Teamleader Focus |\n| `teamleader_link_contact_to_company` | Link a contact to a company, optionally with position and decision maker flag |\n| `teamleader_unlink_contact_from_company` | Unlink a contact from a company in Teamleader Focus |\n| `teamleader_update_contact_company_link` | Update the position or decision maker flag on an existing contact-company link |\n\n### Companies\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_list_companies` | List companies from Teamleader Focus with optional filtering and pagination |\n| `teamleader_get_company` | Get detailed information about a specific company |\n| `teamleader_create_company` | Create a new company in Teamleader Focus |\n\n### Deals\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_list_deals` | List deals/opportunities from Teamleader Focus with optional filtering and pagination |\n| `teamleader_get_deal` | Get detailed information about a specific deal |\n| `teamleader_create_deal` | Create a new deal/opportunity in Teamleader Focus |\n| `teamleader_update_deal` | Update an existing deal in Teamleader Focus |\n\n### Tasks\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_list_tasks` | List tasks from Teamleader Focus with optional filtering and pagination |\n| `teamleader_create_task` | Create a new task in Teamleader Focus |\n\n### Events\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_list_events` | List calendar events from Teamleader Focus with optional filtering and pagination |\n| `teamleader_get_event` | Get detailed information about a specific event |\n| `teamleader_create_event` | Create a new calendar event in Teamleader Focus |\n\n### Invoices\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_list_invoices` | List invoices from Teamleader Focus with optional filtering and pagination |\n| `teamleader_get_invoice` | Get detailed information about a specific invoice |\n| `teamleader_create_invoice` | Create a new draft invoice in Teamleader Focus |\n| `teamleader_invoices_book` | Book a draft invoice into accounting and assign it a number |\n| `teamleader_invoices_send` | Send an invoice by email to the specified recipients |\n| `teamleader_invoices_register_payment` | Register a payment against an invoice |\n| `teamleader_invoices_download` | Get a temporary download URL for an invoice in the specified format |\n\n### Quotations\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_quotations_list` | List quotations, optionally filtered by deal id |\n| `teamleader_quotations_info` | Get a single quotation by id |\n| `teamleader_quotations_create` | Create a quotation on a deal, providing one or more line items |\n| `teamleader_quotations_update` | Update a quotation's line items |\n| `teamleader_quotations_accept` | Accept a quotation (marks it accepted — hard to undo) |\n| `teamleader_quotations_send` | Send a quotation by email to the customer |\n\n### Products\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_products_list` | List products, optionally filtered by search term |\n| `teamleader_products_info` | Get a single product by id |\n| `teamleader_product_categories_list` | List product categories |\n| `teamleader_price_lists_list` | List price lists |\n| `teamleader_units_of_measure_list` | List units of measure |\n\n### Reference Data\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_deal_phases_list` | List deal phases |\n| `teamleader_deal_pipelines_list` | List deal pipelines |\n| `teamleader_deal_sources_list` | List deal sources |\n| `teamleader_lost_reasons_list` | List lost reasons for deals |\n| `teamleader_tax_rates_list` | List tax rates |\n| `teamleader_payment_terms_list` | List payment terms |\n| `teamleader_withholding_tax_rates_list` | List withholding tax rates |\n\n### Organisation\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_users_list` | List users, optionally filtered by search term |\n| `teamleader_users_info` | Get a single user by id |\n| `teamleader_users_me` | Get the currently authenticated user |\n| `teamleader_teams_list` | List teams |\n| `teamleader_departments_list` | List departments |\n\n### Custom Fields\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_custom_field_definitions_list` | List custom field definitions |\n| `teamleader_custom_field_definitions_info` | Get a single custom field definition by id |\n\n### Credit Notes\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_credit_notes_list` | List credit notes, optionally filtered by invoice or department |\n| `teamleader_credit_notes_info` | Get a single credit note by id |\n\n### Subscriptions\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_subscriptions_list` | List subscriptions, optionally filtered by customer |\n| `teamleader_subscriptions_info` | Get a single subscription by id |\n| `teamleader_subscriptions_create` | Create a new subscription (starts recurring invoicing for the customer) |\n| `teamleader_subscriptions_update` | Update a subscription's title |\n| `teamleader_subscriptions_deactivate` | Deactivate a subscription (stops future invoicing) |\n\n### Projects\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_projects_list` | List projects, optionally filtered by search term or customer |\n| `teamleader_projects_info` | Get a single project by id |\n| `teamleader_projects_create` | Create a new project for a customer |\n| `teamleader_milestones_list` | List milestones, optionally filtered by project |\n| `teamleader_milestones_create` | Create a milestone on a project |\n\n### Time Tracking\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_time_tracking_list` | List time tracking entries, optionally filtered by user |\n| `teamleader_time_tracking_add` | Add a time tracking entry |\n| `teamleader_time_tracking_update` | Update a time tracking entry's duration or description |\n| `teamleader_timer_start` | Start a running timer |\n| `teamleader_timer_stop` | Stop a running timer and create a time tracking entry |\n\n### Activities (Calls & Meetings)\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_calls_list` | List calls, optionally filtered by customer |\n| `teamleader_calls_create` | Create a call activity |\n| `teamleader_calls_complete` | Mark a call as completed |\n| `teamleader_meetings_list` | List meetings |\n| `teamleader_meetings_create` | Schedule a meeting |\n| `teamleader_meetings_complete` | Mark a meeting as completed |\n\n### Tickets\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_tickets_list` | List support tickets, optionally filtered by customer or status |\n| `teamleader_tickets_info` | Get a single support ticket by id |\n| `teamleader_tickets_create` | Create a new support ticket for a customer |\n| `teamleader_tickets_update` | Update a ticket's subject or status |\n| `teamleader_tickets_add_message` | Add a reply/message to a ticket thread |\n| `teamleader_ticket_status_list` | List all available ticket statuses |\n\n### Tags\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_contacts_add_tags` | Add one or more tags to a contact |\n| `teamleader_contacts_remove_tags` | Remove one or more tags from a contact |\n| `teamleader_companies_add_tags` | Add one or more tags to a company |\n| `teamleader_companies_remove_tags` | Remove one or more tags from a company |\n\n### Notes\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_notes_list` | List notes linked to a subject (contact, company, deal, etc.) |\n| `teamleader_notes_create` | Create a note linked to a subject |\n\n### Files\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_files_list` | List files linked to a subject (contact, company, deal, etc.) |\n| `teamleader_files_download` | Get a temporary download URL for a file by its ID |\n| `teamleader_files_upload` | Initiate a two-step file upload and return the upload URL |\n\n### Webhooks\n\n| Tool | Description |\n|------|-------------|\n| `teamleader_webhooks_list` | List registered webhooks |\n| `teamleader_webhooks_register` | Register a webhook URL for the given event types |\n| `teamleader_webhooks_unregister` | Unregister a webhook URL for the given event types |\n\n---\n\n## 💬 Example Prompts\n\n```\nCreate a quotation for deal <id> with two line items: 5 hours of consulting at €150/h and a one-time setup fee of €500.\n```\n\n```\nBook the draft invoice <id> into accounting and then send it to the customer.\n```\n\n```\nRegister a €1 200 payment against invoice <id> received today via bank transfer.\n```\n\n```\nLog 2.5 hours on project <id> for user <user_id> with the note \"API integration work\".\n```\n\n```\nStart a timer for me right now — I'm working on the BoostU onboarding project.\n```\n\n```\nOpen a support ticket for company <id>: subject \"Login not working\", priority high.\n```\n\n```\nWhat deal phase IDs do we have in pipeline <id>? I need to move deal <id> to the \"Proposal sent\" phase.\n```\n\n```\nList all products in the \"Hosting\" category and their prices.\n```\n\n```\nCreate a monthly subscription for company <id>: product <product_id>, quantity 1, starting next month.\n```\n\n```\nShow me all open deals with their current phases and tell me which ones haven't moved in the last 30 days.\n```\n\n---\n\n## 🐳 Docker\n\n```bash\ndocker run --rm \\\n  -e TEAMLEADER_CLIENT_ID=your-client-id \\\n  -e TEAMLEADER_CLIENT_SECRET=your-client-secret \\\n  -e TEAMLEADER_REFRESH_TOKEN=your-refresh-token \\\n  -e TEAMLEADER_TOKEN_STORE=/data/teamleader-token \\\n  -v /var/run/teamleader:/data \\\n  ghcr.io/boostuagency/boostu-teamleader-mcp\n```\n\n---\n\n## 🛠️ Development\n\n```bash\n# Clone and install\ngit clone https://github.com/boostuagency/boostu-teamleader-mcp.git\ncd boostu-teamleader-mcp\nnpm install\n\n# Run in development mode (no build step required)\nnpm run dev\n\n# Build\nnpm run build\n\n# Run tests\nnpm test\n\n# Type-check only\nnpm run typecheck\n```\n\n---\n\n## 🏗️ Architecture\n\nThe 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](https://teamleader-mcp.boostu.be).\n\n---\n\n## ✅ Endpoint Verification\n\nMost 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](docs/teamleader-endpoints.md).\n\n---\n\n## 🤝 Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, and instructions on adding new tool groups.\n\n---\n\n## 🔒 Security\n\nReport security vulnerabilities to **nick@boostu.be** — do not open a public issue. See [SECURITY.md](SECURITY.md) for the disclosure policy. Never commit `.env` files or `.teamleader-token` to version control; both are listed in `.gitignore`.\n\n---\n\n## ⚖️ Disclaimer\n\nThis 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.\n\n---\n\n## 📄 License\n\nMIT License — Copyright (c) 2026 BoostU Agency. See [NOTICE](NOTICE) for upstream attribution.\n",
  "bytes": 21082,
  "sha": "25cb670800e5eab4b1693c1fc4f57bc3b34b90eba59de86dc3275531dfee3ce4",
  "repo_slug": "boostuagency/boostu-teamleader-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_boostuagency_boostu_teamleader_6b4fe42c/readme"
}