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

| 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 |

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:

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

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

2. Generate Tokens

The easiest way:

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:

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

Make sure your config includes the args array:

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

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

Run mcporter list teamleader to see all tools.

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

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

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

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

Code Style

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

Adding New Tools

1. Add the tool definition in src/tools/
2. Implement the handler
3. Add tests in tests/
4. 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

• Teamleader Focus API Documentation
• Model Context Protocol
• Teamleader Marketplace
• Claude Desktop

License

MIT License - see LICENSE file.

Acknowledgments

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