<h1 align="center">Teamleader MCP Server</h1>

Control Teamleader Focus with natural language through the Model Context Protocol

<a href="#features">Features</a> • <a href="#quick-start">Quick Start</a> • <a href="#installation">Installation</a> • <a href="#tools">Tools</a> • <a href="#examples">Examples</a> • <a href="#contributing">Contributing</a>

---

What is this?

A Model Context Protocol (MCP) server that connects AI assistants like Claude to Teamleader Focus - the all-in-one CRM, invoicing, and project management platform.

Instead of clicking through menus, just ask:

"Find all open deals for Acme Corporation"
"Create an invoice for 20 hours of consulting at €125/hour"
"Schedule a meeting with Sarah from TechStart next Tuesday at 2pm"
"Log 3 hours to the website project with description: frontend development"

---

Screenshots

🖼️ Screenshots coming soon

<details> <summary>Screenshot placeholders</summary>

| Description | Image | |-------------|-------| | Claude Desktop with deal lookup | screenshots/deal-lookup.png | | Invoice creation conversation | screenshots/invoice-creation.png | | Multi-step workflow example | screenshots/workflow.png | | Claude Desktop config | screenshots/config.png |

</details>

---

Features

🏢 CRM

Companies - List, search, create, and update companies
Contacts - Full contact management with company linking
Deals - Pipeline management, move phases, win/lose tracking

💰 Finance

Invoices - Draft, send, book, register payments
Quotations - Create, send, accept, download PDFs
Products - Product catalog management

⏱️ Operations

Time Tracking - Log hours, manage entries, billable tracking
Calendar Events - Create and manage meetings linked to contacts/deals
Email Tracking - Log emails to entities

🔐 Security

OAuth 2.0 with automatic token refresh
Secure credential storage
Rate limiting respect

---

Quick Start

1. Authenticate with Teamleader

npx teamleader-mcp auth

This opens a browser for OAuth login. Your credentials are saved automatically.

2. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "teamleader-mcp"]
    }
  }
}

3. Start Using!

Restart Claude Desktop and ask: "What Teamleader tools do you have access to?"

---

Installation

Prerequisites

Node.js 18 or higher
A Teamleader Focus account
OAuth 2.0 credentials from Teamleader Marketplace

Via npx (Recommended)

No installation needed - runs directly: ``bash npx teamleader-mcp auth # One-time OAuth setup npx teamleader-mcp # Start the MCP server ``

Global Install

npm install -g teamleader-mcp
teamleader-mcp auth

From Source

git clone https://github.com/Weichie-com/teamleader-mcp.git
cd teamleader-mcp
npm install
npm run build

---

OAuth Setup

1. Register Your Integration

Go to Teamleader Marketplace
Create a new integration
Note your client_id and client_secret
Set redirect URI: http://localhost:3000/callback
Required scopes: contacts, companies, deals, invoices, products, timetracking, events, users

2. Generate Tokens

The easiest way: ``bash node scripts/generate-token.js ``

Or manually via OAuth authorization code flow - see OAUTH_CLAUDE_SETUP.md.

3. Configure Environment

cp .env.example .env

Edit .env: ``bash TEAMLEADER_ACCESS_TOKEN=your_access_token TEAMLEADER_CLIENT_ID=your_client_id TEAMLEADER_CLIENT_SECRET=your_client_secret TEAMLEADER_REFRESH_TOKEN=your_refresh_token ``

---

Tools

This server provides 42 tools across all major Teamleader Focus features:

Companies (4 tools)

| Tool | Description | |------|-------------| | teamleader_companies_list | List/search companies | | teamleader_company_info | Get company details | | teamleader_company_create | Create a company | | teamleader_company_update | Update a company |

Contacts (2 tools)

| Tool | Description | |------|-------------| | teamleader_contacts_list | List/search contacts | | teamleader_contact_info | Get contact details |

Deals (7 tools)

| Tool | Description | |------|-------------| | teamleader_deals_list | List deals with filters | | teamleader_deal_info | Get deal details | | teamleader_deal_create | Create a deal | | teamleader_deal_update | Update a deal | | teamleader_deal_move | Move to different phase | | teamleader_deal_win | Mark as won | | teamleader_deal_lose | Mark as lost |

Invoices (7 tools)

| Tool | Description | |------|-------------| | teamleader_invoices_list | List invoices | | teamleader_invoice_info | Get invoice details | | teamleader_invoice_draft | Create draft invoice | | teamleader_invoice_update | Update invoice | | teamleader_invoice_send | Send via email | | teamleader_invoice_book | Book/finalize | | teamleader_invoice_register_payment | Register payment | | teamleader_invoice_delete | Delete invoice |

Quotations (7 tools)

| Tool | Description | |------|-------------| | teamleader_quotations_list | List quotations | | teamleader_quotation_info | Get quotation details | | teamleader_quotation_create | Create quotation | | teamleader_quotation_update | Update quotation | | teamleader_quotation_send | Send via email | | teamleader_quotation_accept | Mark as accepted | | teamleader_quotation_delete | Delete quotation | | teamleader_quotation_download | Get PDF link |

Products (4 tools)

| Tool | Description | |------|-------------| | teamleader_products_list | List products | | teamleader_product_info | Get product details | | teamleader_product_create | Create product | | teamleader_product_update | Update product |

Time Tracking (5 tools)

| Tool | Description | |------|-------------| | teamleader_timetracking_list | List time entries | | teamleader_timetracking_info | Get entry details | | teamleader_timetracking_add | Add time entry | | teamleader_timetracking_update | Update entry | | teamleader_timetracking_delete | Delete entry |

Calendar Events (3 tools)

| Tool | Description | |------|-------------| | teamleader_events_list | List events | | teamleader_event_info | Get event details | | teamleader_event_create | Create event |

Email Tracking (2 tools)

| Tool | Description | |------|-------------| | teamleader_emails_list | List tracked emails | | teamleader_email_track | Log an email |

---

Examples

Natural Language → Actions

"Find all open deals worth more than €10,000" `` → teamleader_deals_list(status: ["open"]) → Filters results by value ``

"Create an invoice for Acme Corp: 20 hours consulting at €125/hour, 30 days payment term" `` → teamleader_companies_list(term: "Acme Corp") → teamleader_invoice_draft(customer_id: "...", grouped_lines: [...]) ``

"Schedule a meeting with John from DataFlow next Tuesday at 2pm" `` → teamleader_contacts_list(term: "John DataFlow") → teamleader_event_create(title: "Meeting", starts_at: "...", contact_ids: [...]) ``

Direct Tool Calls

# List open deals
mcporter call teamleader.teamleader_deals_list status='["open"]'

# Get company info
mcporter call teamleader.teamleader_company_info id="uuid-here"

# Create a time entry
mcporter call teamleader.teamleader_timetracking_add \
  started_at="2026-01-31T09:00:00+01:00" \
  ended_at="2026-01-31T12:00:00+01:00" \
  description="Development work"

---

Configuration Options

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TEAMLEADER_ACCESS_TOKEN | Yes | OAuth access token | | TEAMLEADER_CLIENT_ID | No | OAuth client ID | | TEAMLEADER_CLIENT_SECRET | No | OAuth client secret | | TEAMLEADER_REFRESH_TOKEN | No* | OAuth refresh token | | TEAMLEADER_TOKEN_STORAGE | No | Custom token storage path |

*Required for automatic token refresh (recommended)

Token Refresh Modes

Static Mode: Only ACCESS_TOKEN set. Token expires after 1 hour. Manual refresh needed.

Auto Refresh Mode (Recommended): All four OAuth variables set. Tokens refresh automatically 5 minutes before expiry.

---

Troubleshooting

<details> <summary>Server hangs or times out</summary>

Make sure your config includes the args array:

{
  "command": "node",
  "args": ["/path/to/teamleader-mcp/dist/index.js"]  // ← Required!
}

</details>

<details> <summary>"Unknown tool" error</summary>

Tool names are prefixed with teamleader_. Use teamleader_deal_info, not get-deal.

Run mcporter list teamleader to see all tools. </details>

<details> <summary>401 Unauthorized</summary>

Access tokens expire after 1 hour. Set up automatic refresh with all OAuth variables, or manually refresh your token. </details>

<details> <summary>Rate limiting errors</summary>

Teamleader allows 200 requests/minute. The server respects rate limit headers. Wait and retry, or reduce request frequency. </details>

---

Development

# Build
npm run build

# Watch mode
npm run dev

# Test
npm test              # Watch mode
npm run test:run      # Single run

# Lint
npm run lint

---

Contributing

We welcome contributions! Here's how to help:

Bug Reports & Feature Requests

Open an issue with a clear description
Include steps to reproduce for bugs
For features, explain the use case

Pull Requests

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: npm test
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Code Style

TypeScript with strict mode
Prettier for formatting
ESLint for linting
Descriptive commit messages

Adding New Tools

Add the tool definition in src/tools/
Implement the handler
Add tests in tests/
Update this README

---

Roadmap

[x] npm package publication
[ ] Project management tools (milestones, tasks)
[ ] Webhook support for real-time updates
[ ] Batch operations
[ ] More filter options
[ ] Credit notes support

See ROADMAP.md for details.

---

Related Resources

---

License

MIT License - see LICENSE file.

---

Acknowledgments

Built with ❤️ using the Model Context Protocol by Anthropic.

---

Made by <a href="https://weichie.com">Weichie</a> • Star ⭐ if you find this useful!

teamleader-mcp