Labsco
Sungdaddy logo

TimeChimp MCP Server

★ 4

from Sungdaddy

A server for interacting with the TimeChimp API v2 to manage time tracking and projects.

🔥🔥🔥✓ VerifiedPaid serviceAdvanced setup
#email#automation#lead-gen#payments#devops#git#maps

TimeChimp MCP Server

A comprehensive Model Context Protocol (MCP) server for interacting with TimeChimp API v2. This server provides tools for retrieving and managing all major TimeChimp resources including projects, users, time entries, contacts, customers, tasks, invoices, expenses, mileage, and tags.

Features

  • Projects: Full CRUD operations (Create, Read, Update, Delete) with comprehensive project management including invoicing, budgeting, task/user assignments, and insights
  • Users: Full CRUD operations (Create, Read, Update, Delete) with user management including roles, contracts, tags, and employee information
  • Time Entries: Fetch time entries with date ranges, user/project filtering, and sorting
  • Contacts: Full CRUD operations (Create, Read, Update, Delete) for contact management
  • Customers: Full CRUD operations (Create, Read, Update, Delete) for customer management
  • Tasks: Get task information with project filtering and sorting
  • Invoices: Retrieve invoices with customer and date filtering
  • Expenses: Full CRUD operations (Create, Read, Update, Delete) for expense management with status tracking
  • Mileage: Full CRUD operations (Create, Read, Update, Delete) for mileage management with status tracking and vehicle assignment
  • Mileage Vehicles: Retrieve mileage vehicle information for vehicle assignment
  • Tags: Get tag information for organization and categorization
  • Built as a single JavaScript file for easy deployment
  • Uses TimeChimp API v2 with proper authentication and OData conventions
  • Comprehensive error handling and validation
  • Support for $expand, $count, and all OData query parameters

Claude Desktop Integration

To use this TimeChimp MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration.

Step 1: Clone the Repository

git clone https://github.com/Sungdaddy/TimeyChimpey.git
cd TimeyChimpey
npm install

Step 2: Set Up Your API Key

Create a .env file in the project directory:

echo "TIMECHIMP_API_KEY=your-actual-api-key-here" > .env

Step 3: Configure Claude Desktop

Add the following configuration to your Claude Desktop settings. The location of the configuration file depends on your operating system:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/path/to/your/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Important: Replace /path/to/your/TimeyChimpey with the actual path to where you cloned the repository, and replace your-actual-api-key-here with your actual TimeChimp API key.

Step 4: Restart Claude Desktop

After adding the configuration, restart Claude Desktop completely for the changes to take effect.

Step 5: Verify Integration

Once Claude Desktop restarts, you should be able to use TimeChimp-related commands. Try asking Claude to:

  • "Get all my projects from TimeChimp"
  • "Show me recent time entries"
  • "List all customers"
  • "Create a new expense entry"

Example Configuration

Here's a complete example configuration file:

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/Users/yourname/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Troubleshooting Claude Desktop Integration

  1. Server not connecting: Ensure the path in cwd is correct and points to the directory containing timechimp-mcp-server.js

  2. API key errors: Verify your API key is correct and has proper permissions in TimeChimp

  3. Node.js not found: Make sure Node.js is installed and accessible from the command line

  4. Permission errors: Ensure Claude Desktop has permission to execute Node.js and access the project directory

  5. Configuration not loading: Double-check the JSON syntax in your configuration file - it must be valid JSON

Available Tools in Claude Desktop

Once configured, you'll have access to all 46 TimeChimp tools through Claude Desktop:

  • Projects: Create, read, update, delete projects with insights
  • Users: Manage users with contracts and roles
  • Time Entries: Track and manage time entries
  • Contacts: Full contact management
  • Customers: Complete customer lifecycle management
  • Expenses: Expense tracking with approval workflows
  • Mileage: Mileage tracking with vehicle management
  • And much more...

You can ask Claude to perform any TimeChimp operation naturally, such as "Create a new project for client ABC" or "Show me all pending expenses that need approval."

TimeChimp API v2 Features

Pagination

The server uses TimeChimp's standard pagination parameters:

  • $top: Maximum number of records to return (1-10000, default: 100)
  • $skip: Number of records to skip for pagination

Filtering (OData)

The server supports TimeChimp's OData filtering conventions:

  • Basic filters: name eq 'Project Name'
  • Boolean filters: active eq true
  • Date filters: date eq 2023-12-31
  • DateTime filters: start gt 2023-12-31T23:59:59Z
  • Combined filters: active eq true and name eq 'Project Name'
  • Collection filters: projects/any(project:project/id eq 123)

Sorting (OData)

The server supports OData sorting:

  • Single field: name desc
  • Multiple fields: name desc, createdAt asc
  • Nested properties: address/city asc

Expansion (OData)

The server supports expanding related entities:

  • Single expansion: customer
  • Multiple expansions: customer,projects,tasks
  • Nested expansions: customer/contacts

Count

The server supports counting total results:

  • $count=true: Include total count in response
  • $count=false: Exclude total count (default for performance)

API Endpoints

The server interacts with the following TimeChimp API v2 endpoints:

  • GET /projects - Retrieve projects
  • GET /projects/{id} - Get specific project by ID
  • POST /projects - Create new project
  • PUT /projects/{id} - Update existing project
  • DELETE /projects/{id} - Delete project
  • GET /projects/{id}/insights - Get project insights
  • GET /users - Retrieve users
  • GET /users/{id} - Get specific user by ID
  • POST /users - Create new user
  • PUT /users/{id} - Update existing user
  • GET /times - Retrieve time entries
  • GET /times/{id} - Get specific time entry by ID
  • GET /contacts - Retrieve contacts
  • GET /contacts/{id} - Get specific contact by ID
  • POST /contacts - Create new contact
  • PUT /contacts/{id} - Update existing contact
  • DELETE /contacts/{id} - Delete contact
  • GET /customers - Retrieve customers
  • GET /customers/{id} - Get specific customer by ID
  • POST /customers - Create new customer
  • PUT /customers/{id} - Update existing customer
  • DELETE /customers/{id} - Delete customer
  • GET /tasks - Retrieve tasks
  • GET /tasks/{id} - Get specific task by ID
  • GET /invoices - Retrieve invoices
  • GET /invoices/{id} - Get specific invoice by ID
  • GET /expenses - Retrieve expenses
  • GET /expenses/{id} - Get specific expense by ID
  • POST /expenses - Create new expense
  • PUT /expenses/{id} - Update existing expense
  • DELETE /expenses/{id} - Delete expense
  • PUT /expenses/status - Update expense status (internal)
  • PUT /expenses/clientStatus - Update expense client status (external)
  • GET /expenses/{id}/statusHistory - Get expense status history
  • GET /mileage - Retrieve mileage entries
  • GET /mileage/{id} - Get specific mileage entry by ID
  • POST /mileage - Create new mileage entry
  • PUT /mileage/{id} - Update existing mileage entry
  • DELETE /mileage/{id} - Delete mileage entry
  • PUT /mileage/status - Update mileage status (internal)
  • PUT /mileage/clientStatus - Update mileage client status (external)
  • GET /mileage/{id}/statusHistory - Get mileage status history
  • GET /mileageVehicles - Retrieve mileage vehicles
  • GET /mileageVehicles/{id} - Get specific mileage vehicle by ID
  • GET /tags - Retrieve tags
  • GET /tags/{id} - Get specific tag by ID

All requests are authenticated using the api-key header and support OData query parameters.

Advanced Examples

Complex Filtering

{
  "name": "get_time_entries",
  "arguments": {
    "filter": "date ge 2024-01-01 and date le 2024-01-31 and user/id eq 123 and project/active eq true",
    "expand": "user,project,task",
    "orderby": "date desc, start desc",
    "top": 50
  }
}

Pagination Example

{
  "name": "get_projects",
  "arguments": {
    "top": 25,
    "skip": 50,
    "count": true,
    "orderby": "name asc"
  }
}

Creating and Managing Contacts

// Create a contact
{
  "name": "create_contact",
  "arguments": {
    "name": "Jane Smith",
    "jobTitle": "CEO",
    "email": "jane@company.com",
    "useForInvoicing": true,
    "customers": [{"id": 123}]
  }
}

// Update the contact
{
  "name": "update_contact",
  "arguments": {
    "id": 456,
    "name": "Jane Smith-Johnson",
    "phone": "+1987654321"
  }
}

// Get contact with expanded customers
{
  "name": "get_contact_by_id",
  "arguments": {
    "id": 456,
    "expand": "customers"
  }
}

Creating and Managing Customers

// Create a customer
{
  "name": "create_customer",
  "arguments": {
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "website": "https://acme.com",
    "address": {
      "address": "123 Business St",
      "postalCode": "12345",
      "city": "Business City",
      "country": "USA"
    },
    "paymentPeriod": 30,
    "hourlyRate": 150.00,
    "prospect": false,
    "tags": [{"id": 1}, {"id": 2}],
    "contacts": [{"id": 123}]
  }
}

// Update the customer
{
  "name": "update_customer",
  "arguments": {
    "id": 456,
    "name": "Acme Corporation Ltd",
    "email": "newcontact@acme.com",
    "paymentPeriod": 45,
    "hourlyRate": 175.00
  }
}

// Get customer with expanded contacts and tags
{
  "name": "get_customer_by_id",
  "arguments": {
    "id": 456,
    "expand": "contacts,tags"
  }
}

Creating and Managing Expenses

// Create an expense
{
  "name": "create_expense",
  "arguments": {
    "date": "2024-01-15",
    "notes": "Business lunch with client",
    "quantity": 1,
    "rate": 75.50,
    "billable": true,
    "customer": {"id": 123},
    "project": {"id": 456},
    "user": {"id": 789}
  }
}

// Update the expense
{
  "name": "update_expense",
  "arguments": {
    "id": 123,
    "notes": "Updated: Business lunch with client and partner",
    "rate": 85.00,
    "user": {"id": 789}
  }
}

// Update expense status (approve multiple expenses)
{
  "name": "update_expense_status",
  "arguments": {
    "message": "Approved by manager",
    "expenses": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Get expense status history
{
  "name": "get_expense_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

Creating and Managing Projects

// Create a project with comprehensive settings
{
  "name": "create_project",
  "arguments": {
    "name": "Website Redesign Project",
    "code": "WEB-2024-001",
    "notes": "Complete redesign of company website with modern UI/UX",
    "color": "#3498db",
    "startDate": "2024-01-15",
    "endDate": "2024-06-30",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 125.00,
      "reference": "WEB-2024-INV"
    },
    "budget": {
      "method": "TotalHours",
      "hours": 400,
      "notificationPercentage": 80
    },
    "customer": {"id": 123},
    "managers": [{"id": 456}],
    "tags": [{"id": 1}, {"id": 2}],
    "projectTasks": [
      {
        "active": true,
        "billable": true,
        "hourlyRate": 125.00,
        "budgetHours": 100,
        "task": {"id": 789}
      },
      {
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 80,
        "task": {"id": 790}
      }
    ],
    "projectUsers": [
      {
        "active": true,
        "hourlyRate": 125.00,
        "budgetHours": 200,
        "costHourlyRate": 80.00,
        "user": {"id": 101}
      },
      {
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 200,
        "costHourlyRate": 100.00,
        "user": {"id": 102}
      }
    ]
  }
}

// Update the project with new requirements
{
  "name": "update_project",
  "arguments": {
    "id": 123,
    "name": "Website Redesign Project - Phase 2",
    "endDate": "2024-08-31",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 150.00
    },
    "budget": {
      "method": "TotalHours",
      "hours": 600,
      "notificationPercentage": 85
    },
    "projectTasks": [
      {
        "id": 456,
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 120,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "id": 789,
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 300,
        "costHourlyRate": 90.00,
        "user": {"id": 101}
      }
    ]
  }
}

// Get project insights for performance analysis
{
  "name": "get_project_insights",
  "arguments": {
    "id": 123
  }
}

// Get project with expanded relationships
{
  "name": "get_project_by_id",
  "arguments": {
    "id": 123,
    "expand": "customer,managers,tags,projectTasks,projectUsers"
  }
}

Creating and Managing Users

// Create a user with contract and role assignment
{
  "name": "create_user",
  "arguments": {
    "userName": "john.doe@company.com",
    "displayName": "John Doe",
    "language": "en",
    "role": {"id": 2},
    "sendInvitation": true,
    "contracts": [
      {
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 75.00,
        "costHourlyRate": 50.00,
        "contractNumber": "EMP-2024-001",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Update the user with new role and contract terms
{
  "name": "update_user",
  "arguments": {
    "id": 123,
    "displayName": "John Doe - Senior Developer",
    "language": "en",
    "employeeNumber": "EMP-001",
    "badgeNumber": "BADGE-001",
    "citizenServiceNumber": "123456789",
    "role": {"id": 3},
    "tags": [{"id": 1}, {"id": 2}],
    "contracts": [
      {
        "id": 456,
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 85.00,
        "costHourlyRate": 55.00,
        "contractNumber": "EMP-2024-001-UPD",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Get user with expanded relationships
{
  "name": "get_user_by_id",
  "arguments": {
    "id": 123,
    "expand": "role,team,tags,contracts,selfBilling,customSchedule"
  }
}

// Get users with filtering and expansion
{
  "name": "get_users",
  "arguments": {
    "filter": "active eq true and role/name eq 'Developer'",
    "expand": "role,contracts",
    "orderby": "displayName asc",
    "top": 50
  }
}

Creating and Managing Mileage

// Create a mileage entry
{
  "name": "create_mileage",
  "arguments": {
    "date": "2024-01-15",
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City",
    "notes": "Client meeting and project consultation",
    "distance": 45.5,
    "billable": true,
    "type": "Business",
    "customer": {"id": 123},
    "project": {"id": 456},
    "vehicle": {"id": 789},
    "user": {"id": 101}
  }
}

// Update the mileage entry
{
  "name": "update_mileage",
  "arguments": {
    "id": 123,
    "notes": "Updated: Client meeting, project consultation, and site inspection",
    "distance": 52.3,
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City (with site inspection)",
    "type": "Business",
    "user": {"id": 101}
  }
}

// Update mileage status (approve multiple mileage entries)
{
  "name": "update_mileage_status",
  "arguments": {
    "message": "Approved by manager after review",
    "mileages": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Update mileage client status
{
  "name": "update_mileage_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved mileage claims",
    "mileages": [{"id": 123}, {"id": 124}]
  }
}

// Get mileage status history
{
  "name": "get_mileage_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

// Get mileage entries with filtering
{
  "name": "get_mileage",
  "arguments": {
    "user_id": "101",
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "filter": "type eq 'Business' and billable eq true",
    "expand": "user,project,customer,vehicle",
    "orderby": "date desc"
  }
}

// Get mileage vehicles
{
  "name": "get_mileage_vehicles",
  "arguments": {
    "active_only": true,
    "expand": "users",
    "orderby": "brand asc"
  }
}

// Get specific mileage vehicle with users
{
  "name": "get_mileage_vehicle_by_id",
  "arguments": {
    "id": 789,
    "expand": "users"
  }
}

Error Handling

The server includes comprehensive error handling:

  • Authentication errors: When API key is missing or invalid
  • API errors: When TimeChimp API returns error responses (including 429 rate limiting)
  • Network errors: When requests fail due to connectivity issues
  • Validation errors: When invalid parameters are provided
  • OData errors: When invalid filter or orderby expressions are used

Error responses include detailed error messages to help with debugging.

Development

Project Structure

TimeJS/
├── timechimp-mcp-server.js    # Main server file
├── package.json               # Node.js dependencies and scripts
└── README.md                  # This file

Adding New Tools

To add new tools:

  1. Add the tool definition to the ListToolsRequestSchema handler
  2. Add a case for the tool in the CallToolRequestSchema handler
  3. Implement the tool method in the TimechimpMCPServer class
  4. Use the generic handleGetRequest or handleGetByIdRequest methods for consistency

Testing

You can test the server using any MCP client or by running it directly and sending JSON-RPC messages via stdin.

Support

For issues related to:

  • This MCP server: Open an issue in this repository
  • TimeChimp API: Contact TimeChimp support at ict@timechimp.com
  • MCP protocol: Check the Model Context Protocol documentation

Changelog

v0.7.0

  • Added full CRUD operations for mileage (Create, Read, Update, Delete)
  • Added mileage status management with internal and external status updates
  • Added mileage status history tracking functionality
  • Added mileage vehicle management (Read operations)
  • Enhanced mileage management with comprehensive linking to customers, projects, vehicles, and users
  • Added bulk status update capabilities for mileage (up to 100 entries at once)
  • Updated tool count to 46 total tools
  • Added mileage CRUD examples to documentation

v0.6.0

  • Added full CRUD operations for users (Create, Read, Update, Delete)
  • Added user contract management and role assignment
  • Updated tool count to 38 total tools
  • Added user CRUD examples to documentation

v0.5.0

  • Added full CRUD operations for projects (Create, Read, Update, Delete)
  • Added project insights functionality
  • Updated tool count to 36 total tools
  • Added project CRUD examples to documentation

v0.4.0

  • Added full CRUD operations for expenses (Create, Read, Update, Delete)
  • Added expense status management with internal and external status updates
  • Added expense status history tracking functionality
  • Enhanced expense management with comprehensive linking to customers, projects, products, users, and VAT rates
  • Added bulk status update capabilities (up to 100 expenses at once)
  • Updated tool count to 32 total tools
  • Added expense CRUD examples to documentation

v0.3.0

  • Added full CRUD operations for customers (Create, Read, Update, Delete)
  • Added comprehensive customer management with address, payment terms, rates, and relationships
  • Enhanced customer tools with support for VAT rates, tags, and contact linking
  • Updated tool count to 26 total tools
  • Added customer CRUD examples to documentation

v0.2.0

  • Added comprehensive support for all major TimeChimp API v2 endpoints
  • Added full CRUD operations for contacts (Create, Read, Update, Delete)
  • Added support for customers, tasks, invoices, expenses, mileage, and tags
  • Added generic request handlers for consistency and maintainability
  • Enhanced OData support with $expand, $count, and improved filtering
  • Added individual "get by ID" tools for all resource types
  • Improved error handling and validation
  • Updated API version header to 2.0

v0.1.0

  • Initial release
  • Support for GetProjects, Users, and TimeEntries tools
  • TimeChimp API v2 integration with OData support
  • Comprehensive error handling and validation
  • Default sorting for projects (most recent first)