TimeChimp

You can run a TimeChimp MCP Server locally to access TimeChimp API v2 data through a single, configurable MCP endpoint. This server handles authentication, OData-style querying, and a wide range of resources such as projects, users, time entries, contacts, customers, tasks, invoices, expenses, mileage, and tags. It’s designed for easy deployment and seamless integration with MCP clients.

How to use

Start the MCP server as described below, then connect your MCP client to the local process or to a remote service that exposes the MCP endpoint. Use your MCP client to issue commands that retrieve, create, update, or delete TimeChimp data through the server. The server supports common operations for projects, users, time entries, contacts, customers, tasks, invoices, expenses, mileage, and tags, with OData-style filtering, expansion, and counting. You can perform bulk updates for certain resources and receive structured responses that include status and data.

Typical usage patterns include listing records with filters, expanding related entities, retrieving by ID, and performing create/update/delete operations. When you start the server, it will require an API key for TimeChimp authentication. Store this key securely and supply it to the server via environment variables so all outgoing requests to TimeChimp API v2 are authenticated.

How to install

Prerequisites you must have before installing the MCP server:

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

Step-by-step installation and startup flow you can follow exactly:

# Step 1: Prepare your project folder
# Clone a copy containing the MCP server code or place the server file in your project
# Example if you already have the project directory

# Step 2: Install dependencies
npm install

# Step 3: Ensure the server file is executable if required
chmod +x timechimp-mcp-server.js

# Step 4: Set the API key for TimeChimp access
export TIMECHIMP_API_KEY="your-api-key-here"

# Step 5: Start the server
npm start
# or run directly
node timechimp-mcp-server.js

# Optional: development mode with debugging
npm run dev

Configuration and security

Set up authentication for TimeChimp API calls by providing your API key to the MCP server. The key is passed via environment variables so every request to TimeChimp API v2 is properly authenticated. Use the environment variable TIMECHIMP_API_KEY to supply your key.

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

Claude Desktop integration example

If you connect Claude Desktop to this MCP server, configure a stdio-based server entry that launches the MCP server and passes the API key. The following configuration shows a typical setup.

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

Running the server and verification

To run the server locally, start it with your preferred method and verify that you can connect with your MCP client. You should be able to perform operations such as listing projects, retrieving users, and querying time entries. If you encounter authentication errors, re-check that TIMECHIMP_API_KEY is correctly set and has the necessary permissions.

Additional notes

The MCP server is designed to support OData-style query parameters, including $expand, $count, and standard filters and sort orders. Use these features to tailor responses to your needs, such as expanding related entities or filtering results by date, status, or other fields.

Available tools

get_projects

Retrieve projects with optional filtering, counting, and expansion of related entities.

get_project_by_id

Fetch a single project by its ID with optional expansions.

create_project

Create a new project with invoicing, budget, and linked entities.

update_project

Update an existing project with new values and linked resources.

delete_project

Remove a project by its ID.

get_project_insights

Retrieve insights like hours and budget for a project.

get_users

Retrieve users with optional filtering, pagination, and expansions.

get_user_by_id

Fetch a single user by ID with optional expansions.

create_user

Create a new user with contracts and roles.

update_user

Update an existing user with new details and contracts.

get_time_entries

Retrieve time entries with optional user/project/date filtering and sorting.

get_time_entry_by_id

Get a specific time entry by ID with optional expansions.

get_contacts

Retrieve contacts with optional expansions and filtering.

get_contact_by_id

Fetch a single contact by ID with optional expansions.

create_contact

Create a new contact and link to customers if needed.

update_contact

Update an existing contact with new details.

delete_contact

Delete a contact by ID.

get_customers

Retrieve customers with optional filtering and expansions.

get_customer_by_id

Fetch a customer by ID with optional expansions.

create_customer

Create a new customer with addresses and payment terms.

update_customer

Update an existing customer with new data.

delete_customer

Delete a customer by ID.

get_tasks

Retrieve tasks with optional project filtering and sorting.

get_task_by_id

Fetch a task by ID with optional expansions.

get_invoices

Retrieve invoices with customer/date filtering and expansions.

get_invoice_by_id

Fetch a specific invoice by ID with optional expansions.

get_expenses

Retrieve expenses with optional filters and expansions.

get_expense_by_id

Get a specific expense by its ID.

create_expense

Create a new expense linked to customer/project/user.

update_expense

Update an existing expense with new details.

delete_expense

Delete an expense by ID.

update_expense_status

Update internal status of expenses in bulk.

update_expense_client_status

Update external client-facing status of expenses in bulk.

get_expense_status_history

Query history of expense status changes.

get_mileage

Retrieve mileage entries with optional filters and expansions.

get_mileage_by_id

Fetch a mileage entry by ID with optional expansions.

create_mileage

Create a mileage entry linked to a vehicle/project/customer.

update_mileage

Update an existing mileage entry.

delete_mileage

Delete a mileage entry by ID.

update_mileage_status

Update internal mileage status in bulk.

update_mileage_client_status

Update external client status for mileage entries.

get_mileage_status_history

Query mileage status history records.

get_mileage_vehicles

Retrieve mileage vehicles with optional expansions.

get_mileage_vehicle_by_id

Fetch a mileage vehicle by ID with optional expansions.

get_tags

Retrieve tags with optional filtering and expansions.

get_tag_by_id

Fetch a tag by ID with optional expansions.