TimeChimp MCP Server

How to use

You connect to the MCP server using a compatible MCP client. The server exposes a wide range of tools that let you perform CRUD operations, fetch data with date ranges and filters, and expand related data using OData query parameters. You can retrieve lists of resources, fetch individual items by ID, create new records, update existing ones, and delete entries. All requests are authenticated with an API key and support $expand, $count, and other OData features for flexible querying.

How to install

Follow these concrete steps to install and run the TimeChimp MCP Server locally.

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

# Step 1: Clone the project
git clone <repository-url>
cd TimeJS

# Step 2: Install dependencies
npm install

# Step 3: Make the server executable (if you will run it directly)
chmod +x timechimp-mcp-server.js

# Step 4: Start the server (direct start)
node timechimp-mcp-server.js

# Optional: Development with debugging
npm run dev

Configuration and usage notes

Configure the API key as an environment variable to authorize calls to TimeChimp API v2. The server expects the TIMECHIMP_API_KEY variable. You can set it in your shell or place it in a .env file.

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

Or in a .env file:
```
TIMECHIMP_API_KEY=your-api-key-here

Claude Desktop integration (example configuration)

If you want to use Claude Desktop with this MCP server, configure Claude to run the MCP server as a local process. The following example shows a complete configuration that runs the server via Node and passes the API key through the environment.

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

Running the server and tools overview

To run the server, start with the command shown in the installation steps. Once running, you can invoke a wide range of tools such as get_projects, get_project_by_id, create_project, update_project, delete_project, get_users, get_time_entries, get_contacts, get_customers, get_tasks, get_invoices, get_expenses, get_mileage, and more. Each tool accepts OData-like filters, expansions, and sorting to tailor queries to your needs.

Troubleshooting and tips

If you encounter authentication errors, verify that TIMECHIMP_API_KEY is set correctly and has API access. For API rate limits, wait and retry, or implement client-side throttling. Ensure Node.js is installed and the server process has permission to execute. Validate JSON schemas and OData expressions for proper syntax.

Notes on security and best practices

Protect your API key and avoid exposing it in client-side code or logs. Use a secure environment to store credentials and rotate keys periodically. When deploying publicly, limit access to the MCP server and monitor usage to prevent unauthorized operations.

get_projects

Retrieve a list of projects with optional top, skip, count, expand, active_only, filter, and orderby parameters.

get_project_by_id

Fetch a single project by its ID with optional expansion of related data.

create_project

Create a new project with detailed invoicing, budget, customers, managers, tags, tasks, and users configuration.

update_project

Update an existing project with full invoicing and budget options, and linked tasks/users.

delete_project

Delete a project by its ID.

get_project_insights

Retrieve insights for a specific project, including hours, budget, costs, and revenue.

get_users

Retrieve a list of users with optional filtering, expansion, and sorting.

get_user_by_id

Fetch a single user by ID with related data expansion.

create_user

Create a new user with optional contracts and role assignments.

update_user

Update an existing user including contracts, roles, and tags.

get_time_entries

Retrieve time entries with date ranges and optional user/project filters.

get_time_entry_by_id

Fetch a specific time entry by ID.

get_contacts

Retrieve contacts with optional expansion and filters.

get_contact_by_id

Fetch a single contact by ID.

create_contact

Create a new contact with related customer links.

update_contact

Update an existing contact and its linked customers.

delete_contact

Delete a contact by ID.

get_customers

Retrieve customers with optional expansion and filtering.

get_customer_by_id

Fetch a single customer by ID with related data expansion.

create_customer

Create a new customer with address, payment terms, and linked tags/contacts.

update_customer

Update an existing customer and its related data.

delete_customer

Delete a customer by ID.

get_tasks

Retrieve tasks with optional project filtering and expansion.

get_task_by_id

Fetch a task by ID with optional expansions.

get_invoices

Retrieve invoices with customer and date filtering.

get_invoice_by_id

Fetch a single invoice by ID with optional expansion.

get_expenses

Retrieve expenses with date filters and related links.

get_expense_by_id

Fetch a single expense by ID with optional expansion.

create_expense

Create a new expense with linked customer/project/user and VAT rate.

update_expense

Update an existing expense with details and linked entities.

delete_expense

Delete an expense by ID.

update_expense_status

Update internal expense status for approval/invoicing.

update_expense_client_status

Update external client status for expenses in client portal workflows.

get_expense_status_history

Query status history records for a given expense.

get_mileage

Retrieve mileage entries with filters and expansions.

get_mileage_by_id

Fetch a mileage entry by ID.

create_mileage

Create a mileage entry linked to customer, project, vehicle, and user.

update_mileage

Update an existing mileage entry.

delete_mileage

Delete a mileage entry by ID.

update_mileage_status

Update internal mileage status for approval/invoicing.

update_mileage_client_status

Update external mileage client status in client portal scenarios.

get_mileage_status_history

Query mileage status history records.

get_mileage_vehicles

Retrieve mileage vehicles with optional expansion.

get_mileage_vehicle_by_id

Fetch a mileage vehicle by ID with optional expansions.

get_tags

Retrieve tags for organization and categorization.

get_tag_by_id

Fetch a single tag by ID with optional expansion.