TimeChimp MCP Server

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

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.

- 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

- Node.js 18.0.0 or higher
- A TimeChimp account with API access
- TimeChimp API key

git clone <repository-url> cd TimeJS

You need to set your TimeChimp API key as an environment variable:

export TIMECHIMP_API_KEY="your-api-key-here"

- Log in to your TimeChimp account
- Go to your profile settings
- Navigate to the API section
- Generate or copy your API key

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

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

Create a.envfile in the project directory:

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

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.jsonWindows:%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/TimeyChimpeywith the actual path to where you cloned the repository, and replaceyour-actual-api-key-herewith your actual TimeChimp API key.

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

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"

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

Server not connecting: Ensure the path incwdis correct and points to the directory containingtimechimp-mcp-server.js

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

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

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

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

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

# Start the server npm start # Or run directly node timechimp-mcp-server.js # For development with debugging npm run dev

- top(number, optional): Maximum number of projects to return (1-10000, default: 100)
- skip(number, optional): Number of projects to skip for pagination (default: 0)
- count(boolean, optional): Whether to include the total count of results (default: true)
- expand(string, optional): Comma-delimited list of properties to expand (e.g., "customer,tasks")
- active_only(boolean, optional): Only return active projects (default: false)
- filter(string, optional): OData filter expression
- orderby(string, optional): OData orderby expression

{ "name": "get_projects", "arguments": { "top": 50, "active_only": true, "expand": "customer,tasks", "orderby": "name desc" } }

- id(number, required): Project ID
- expand(string, optional): Comma-delimited list of properties to expand

{ "name": "get_project_by_id", "arguments": { "id": 123, "expand": "customer,tasks" } }

- name(string, required): The project name
- active(boolean, optional): Whether the project can be used (default: true)
- code(string, optional): The project code
- notes(string, optional): The project description
- color(string, optional): The project color
- startDate(string, optional): The project start date (YYYY-MM-DD format)
- endDate(string, optional): The project end date (YYYY-MM-DD format)
- invoicing(object, optional): The project invoicing settings

- method(string, optional): The project invoicing method used

- Allowed values:NoInvoicing,TaskHourlyRate,UserHourlyRate,ProjectHourlyRate,CustomerHourlyRate,ProjectRate,TaskRate

- method(string, optional): The project budget method used

- Allowed values:NoBudget,TotalHours,TaskHours,UserHours,TotalRate,TaskRate,TotalCost

- id(number, required): Unique identifier for the customer

- id(number, required): Unique identifier for the project

{ "name": "create_project", "arguments": { "name": "Website Redesign", "code": "WEB-2024", "notes": "Complete redesign of company website", "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, "task": {"id": 789} } ], "projectUsers": [ { "active": true, "hourlyRate": 125.00, "budgetHours": 200, "user": {"id": 101} } ] } }

- id(number, required): Project ID
- name(string, required): The project name
- active(boolean, optional): Whether the project can be used
- code(string, optional): The project code
- notes(string, optional): The project description
- color(string, optional): The project color
- startDate(string, optional): The project start date (YYYY-MM-DD format)
- endDate(string, optional): The project end date (YYYY-MM-DD format)
- invoicing(object, required): The project invoicing settings

- method(string, optional): The project invoicing method used

- Allowed values:NoInvoicing,TaskHourlyRate,UserHourlyRate,ProjectHourlyRate,CustomerHourlyRate,ProjectRate,TaskRate,Subscription

- method(string, optional): The project budget method used

- Allowed values:NoBudget,TotalHours,TaskHours,UserHours,TotalRate,TaskRate,Invoiced,TotalCost

- id(number, required): Unique identifier for the customer

- id(number, required): Unique identifier for the project

{ "name": "update_project", "arguments": { "id": 123, "name": "Website Redesign - 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} } ] } }

{ "name": "delete_project", "arguments": { "id": 123 } }

Get project insights including hours, budget, costs, and revenue data.

{ "name": "get_project_insights", "arguments": { "id": 123 } }

- top(number, optional): Maximum number of users to return (1-10000, default: 100)
- skip(number, optional): Number of users to skip for pagination (default: 0)
- count(boolean, optional): Whether to include the total count of results (default: true)
- expand(string, optional): Comma-delimited list of properties to expand
- active_only(boolean, optional): Only return active users (default: false)
- filter(string, optional): OData filter expression
- orderby(string, optional): OData orderby expression

{ "name": "get_users", "arguments": { "top": 100, "filter": "firstName eq 'John' and active eq true", "orderby": "lastName asc" } }

- id(number, required): User ID
- expand(string, optional): Comma-delimited list of properties to expand

Create a new user (note: adding users can result in additional invoice and extra cost).

- userName(string, required): The user email address
- displayName(string, required): The user name
- language(string, optional): The user language (default: en)

- Allowed values:en,nl,de,pl,fr,es

- id(number, required): Unique identifier for the role

- startDate(string, optional): The contract start date (YYYY-MM-DD format, default: UTC today)
- endDate(string, optional): The contract end date (YYYY-MM-DD format)
- weekHours(number, optional): The contract hours per week
- hourlyRate(number, optional): The contract sales hourly rate
- costHourlyRate(number, optional): The contract purchase hourly rate
- contractNumber(string, optional): The contract number
- contractType(object, required): Contract type to be linked to the contract

- id(number, required): Unique identifier for the contract type

{ "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} } ] } }

- id(number, required): User ID
- displayName(string, required): The user name
- language(string, optional): The user language (default: en)

- Allowed values:en,nl,de,pl,fr,es

- id(number, required): Unique identifier for the role

- id(number, optional): Unique identifier for the user contract (can be null if new user contract needs to be added)
- startDate(string, optional): The contract start date (YYYY-MM-DD format, default: UTC today)
- endDate(string, optional): The contract end date (YYYY-MM-DD format)
- weekHours(number, optional): The contract hours per week
- hourlyRate(number, optional): The contract sales hourly rate
- costHourlyRate(number, optional): The contract purchase/cost hourly rate
- contractNumber(string, optional): The contract number
- contractType(object, required): Contract type to be linked with the contract

- id(number, required): Unique identifier for the contract type

{ "name": "update_user", "arguments": { "id": 123, "displayName": "John Doe - Senior Developer", "language": "en", "employeeNumber": "EMP-001", "badgeNumber": "BADGE-001", "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} } ] } }

- top(number, optional): Maximum number of time entries to return (1-10000, default: 100)
- skip(number, optional): Number of time entries to skip for pagination (default: 0)
- count(boolean, optional): Whether to include the total count of results (default: true)
- expand(string, optional): Comma-delimited list of properties to expand (e.g., "user,project,task")
- user_id(string, optional): Filter by specific user ID
- project_id(string, optional): Filter by specific project ID
- from_date(string, optional): Start date for filtering (YYYY-MM-DD format)
- to_date(string, optional): End date for filtering (YYYY-MM-DD format)
- filter(string, optional): OData filter expression
- orderby(string, optional): OData orderby expression

{ "name": "get_time_entries", "arguments": { "top": 100, "from_date": "2024-01-01", "to_date": "2024-01-31", "user_id": "123", "expand": "user,project,task", "orderby": "date desc" } }

- id(number, required): Time entry ID
- expand(string, optional): Comma-delimited list of properties to expand

- top(number, optional): Maximum number of contacts to return (1-10000, default: 100)
- skip(number, optional): Number of contacts to skip for pagination (default: 0)
- count(boolean, optional): Whether to include the total count of results (default: true)
- expand(string, optional): Comma-delimited list of properties to expand (e.g., "customers")
- active_only(boolean, optional): Only return active contacts (default: false)
- filter(string, optional): OData filter expression
- orderby(string, optional): OData orderby expression

{ "name": "get_contacts", "arguments": { "top": 50, "expand": "customers", "filter": "name eq 'John Doe'", "orderby": "name asc" } }

- id(number, required): Contact ID
- expand(string, optional): Comma-delimited list of properties to expand

- name(string, required): The contact name
- jobTitle(string, optional): The contact job title
- email(string, optional): The contact email address
- phone(string, optional): The contact phone number
- useForInvoicing(boolean, optional): Whether the contact info will be used for invoicing (default: false)
- active(boolean, optional): Whether the contact can be used (default: true)
- customers(array, optional): List of customer IDs to link to this contact

{ "name": "create_contact", "arguments": { "name": "John Doe", "jobTitle": "Project Manager", "email": "john.doe@example.com", "phone": "+1234567890", "useForInvoicing": true, "customers": [{"id": 123}, {"id": 456}] } }

- id(number, required): Contact ID
- name(string, required): The contact name
- jobTitle(string, optional): The contact job title
- email(string, optional): The contact email address
- phone(string, optional): The contact phone number
- useForInvoicing(boolean, optional): Whether the contact info will be used for invoicing
- active(boolean, optional): Whether the contact can be used
- customers(array, optional): List of customer IDs to link to this contact

{ "name": "delete_contact", "arguments": { "id": 123 } }

- top(number, optional): Maximum number of customers to return (1-10000, default: 100)
- skip(number, optional): Number of customers to skip for pagination (default: 0)
- count(boolean, optional): Whether to include the total count of results (default: true)
- expand(string, optional): Comma-delimited list of properties to expand (e.g., "contacts,projects")
- active_only(boolean, optional): Only return active customers (default: false)
- filter(string, optional): OData filter expression
- orderby(string, optional): OData orderby expression

- id(number, required): Customer ID
- expand(string, optional): Comma-delimited list of properties to expand

- name(string, required): The customer name
- active(boolean, optional): Whether the customer can be used (default: true)
- relationId(string, optional): The customer number
- address(object, optional): The customer address info

- address(string, optional): The address line
- postalCode(string, optional): The postal code
- city(string, optional): The city
- country(string, optional): The country

- address(string, optional): The address line
- postalCode(string, optional): The postal code
- city(string, optional): The city
- country(string, optional): The country

- id(number, required): Unique identifier for the vat rate

{ "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}] } }

- id(number, required): Customer ID
- name(string, required): The customer name
- active(boolean, optional): Whether the customer can be used
- relationId(string, optional): The customer number
- address(object, optional): The customer address info

- address(string, optional): The address line
- postalCode(string, optional): The postal code
- city(string, optional): The city
- country(string, optional): The country

- address(string, optional): The address line
- postalCode(string, optional): The postal code
- city(string, optional): The city
- country(string, optional): The country

- id(number, required): Unique identifier for the vat rate