Teamleader Mcp— agent skill

<p align="center"> <img src="https://www.teamleader.eu/hs-fs/hubfs/Logos/logo-teamleader-focus.png" alt="Teamleader Focus" width="300"> </p>

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

<p align="center"> <strong>Control Teamleader Focus with natural language through the Model Context Protocol</strong> </p>

<p align="center"> <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> </p>

<p align="center"> <a href="https://www.npmjs.com/package/teamleader-mcp"><img src="https://img.shields.io/npm/v/teamleader-mcp" alt="npm version"></a> <img src="https://img.shields.io/badge/tools-42-blue" alt="42 Tools"> <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"> <img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP Compatible"> <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node >= 18"> </p>

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

<!-- TODO: Add screenshots before public launch -->

<p align="center"> <i>🖼️ Screenshots coming soon</i> </p>

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

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

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)

Contacts (2 tools)

Deals (7 tools)

Invoices (7 tools)

Quotations (7 tools)

Products (4 tools)

Time Tracking (5 tools)

Calendar Events (3 tools)

Email Tracking (2 tools)

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

*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><strong>Server hangs or times out</strong></summary>

Make sure your config includes the args array:

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

</details>

<details> <summary><strong>"Unknown tool" error</strong></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><strong>401 Unauthorized</strong></summary>

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

<details> <summary><strong>Rate limiting errors</strong></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

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.

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