Introduction

Project execution often involves coordinating multiple activities that must finish by specific deadlines to achieve overarching objectives. This unified access point consolidates various functionalities, allowing precise tracking of effort across distinct work components, akin to managing individual assignments within a larger project structure. It provides a single point for interacting with the QuickBooks Time data ecosystem.

Task Dependency Management
Resource Allocation and Coordination
Project Goal Decomposition
Time Entry Standardization
Work Cycle Deadlines

Setup

Installation of necessary libraries requires executing a standard package installation command:

pip install -r requirements.txt

After installation, create a configuration file named .env in the root directory. This file must securely store your authorization credential for the QuickBooks Time service:

QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Claude Desktop Configuration

To integrate this service with the Claude Desktop environment, specific settings must be adjusted within its configuration structure. The following example illustrates how to map a command invocation to the local server:

{
  "globalShortcut": "Ctrl+Q",
  "mcpServers": {
    "qb-time-tools": {
      "command": "python",
      "args": [
        "./qb-time-mcp-server/main.py"
      ],
      "env": {
        "QB_TIME_ACCESS_TOKEN": "your_quickbooks_time_access_token_here"
      }
    }
  }
}

Usage

To initiate the service listener, execute the main script from your system's command line interface:

python main.py

The server begins operations, awaiting structured requests via standard input (stdin) and responding through standard output (stdout).

Available Tools

This server unifies four distinct functional domains, enabling comprehensive data retrieval and manipulation.

JobCode Tools

These functions manage the structure and attributes of defined work items.

get_jobcodes: Retrieves work classifications, supporting detailed filtering criteria.
Basic Filters:
- ids: (array of numbers, optional) A comma-separated list specifying target jobcode identifiers.
- name: (string, optional) Filters results based on the beginning of the jobcode name, allowing wildcard usage (*).
- active: (string, optional) Determines the status inclusion: "yes" (default), "no", or "both".
Type and Hierarchy Filters:
- type: (string, optional) Limits retrieval by type: "regular" (default), "pto", "paid_break", "unpaid_break", or "all".
- parent_ids: (array of numbers, optional) Filters based on parent jobcode identifiers. Use 0 for root items or -1 for all hierarchical levels.
Additional Filters:
- customfields: (boolean, optional) Requests the inclusion of associated custom field definitions.
- modified_before: (string, optional) Filters records updated before a specified ISO 8601 timestamp.
- modified_since: (string, optional) Filters records updated after a specified ISO 8601 timestamp.
- page: (number) Specifies the requested page number for paginated results.
- limit: (number) Sets the maximum number of records returned per page, capped at 200.
get_jobcode: Fetches the details for a single work classification identified by its unique key.
Required Parameters:
- id: (number) The unique identifier of the jobcode needed.
get_jobcode_hierarchy: Returns the complete structural arrangement of jobcodes.
Parameters:
- parent_ids: (array of numbers, optional) Filters based on parent identifiers (0 for top tier, -1 for all levels, or specific IDs).
- active: (string, optional) Filters results by active status: "yes" (default), "no", or "both".
- type: (string, optional) Filters by classification type: "regular" (default), "pto", "paid_break", "unpaid_break", or "all".
- customfields: (boolean, optional) Includes custom field data in the output structure.

Timesheet Tools

These methods facilitate querying and retrieving granular time entries.

get_timesheets: Retrieves records of time entry, supporting extensive filtering.
Required Parameters (one minimum must be provided):
- ids: (array of numbers) A list of specific timesheet identifiers.
- start_date: (string) Retrieves entries commencing on or after this date (format YYYY-MM-DD).
- modified_before: (string) Retrieves entries updated prior to this specific ISO 8601 time.
- modified_since: (string) Retrieves entries updated after this specific ISO 8601 time.
Optional Parameters:
- end_date: (string) Retrieves entries concluding on or before this date (format YYYY-MM-DD).
- user_ids: (array of numbers) Filters results based on the involved user identities.
- group_ids: (array of numbers) Filters results associated with specified organizational groups.
- jobcode_ids: (array of numbers) Filters based on linked jobcode identifiers, including subordinate codes.
- payroll_ids: (array of numbers) Filters records linked to specified payroll processing identifiers.
- on_the_clock: (string) Filters based on real-time status: "yes", "no", or "both" (default: "no").
- jobcode_type: (string) Filters by the time category: "regular", "pto", "paid_break", "unpaid_break", or "all" (default: "all").
- page: (number) Indicates the desired page number for the result set.
- limit: (number) Sets the maximum number of records returned.
get_timesheet: Fetches the complete record for a single time entry using its identifier.
Required Parameters:
- id: (number) The unique identifier corresponding to the timesheet.
get_current_timesheets: Obtains records for employees actively tracking time at the moment of the request.
Required Parameters:
- on_the_clock: (string) This parameter must be set to "yes" for this operation.
Optional Parameters:
- user_ids: (array of numbers) Limits the active check to selected employees.
- group_ids: (array of numbers) Limits the active check to users belonging to specified groups.
- jobcode_ids: (array of numbers) Limits the active check to specific job classifications.
- supplemental_data: (string) Requests additional details in the response: "yes" (default) or "no".

get_users: Retrieves a comprehensive list of system users, supporting many filtering dimensions.
User Identification Filters:
- ids: (array of numbers, optional) Specifies exact user IDs to include.
- not_ids: (array of numbers, optional) Specifies user IDs to explicitly exclude from results.
- employee_numbers: (array of numbers, optional) Filters based on employee identification codes.
- usernames: (array of strings, optional) Filters by exact matching usernames.
Group Filters:
- group_ids: (array of numbers, optional) Includes users who belong to these groups.
- not_group_ids: (array of numbers, optional) Excludes users belonging to these specified groups.
Status and Identification Filters:
- payroll_ids: (array of strings, optional) Filters based on payroll tracking numbers.
- active: (string, optional) Filters by user status: "yes" (default), "no", or "both".
Name Filters:
- first_name: (string, optional) Filters results where the first name matches the provided string (wildcards allowed at the end).
- last_name: (string, optional) Filters results where the last name matches the provided string (wildcards allowed at the end).
Time-Based Filters:
- modified_before: (string, optional) Filters users updated before a given ISO 8601 timestamp.
- modified_since: (string, optional) Filters users updated since a given ISO 8601 timestamp.
Pagination:
- page: (number, optional) The page number requested (defaults to 1).
- per_page: (number, optional) The count of records per page (defaults to 50, maximum 50).
get_user: Retrieves all details for an employee identified by their unique key.
Required Parameters:
- id: (number) The unique ID of the user record sought.
get_current_user: Fetches the data pertaining to the identity currently authenticated against the API.
No parameters required.
Returns comprehensive data including profile, organizational assignment, accrued leave balances, system permissions, and custom data fields.
get_groups: Retrieves definitions for all defined organizational groupings.
Optional Parameters:
- ids: (array of numbers) Limits results to specified group identifiers.
- active: (string) Filters groups by their operational status: "yes" (default), "no", or "both".
- manager_ids: (array of numbers) Filters groups associated with these user managers.
- supplemental_data: (string) Requests inclusion of extra group metadata: "yes" or "no" (default).
Returns group structures, manager assignments, settings for time entries, and break configurations.

Project Management Tools

These functions specifically deal with project records and associated metadata, essential for tracking goal completion.

get_projects: Retrieves a list of defined projects, offering record filtering capabilities.
Optional Parameters:
- ids: (array of numbers) Filters the list to include only specific project identifiers.
- active: (string) Filters by project status: "yes" (default), "no", or "both".
- client_id: (number) Filters based on the linked client identifier.
- jobcode_id: (number) Filters projects associated with a particular work classification.
- modified_before: (string) Filters records updated before a specified ISO 8601 date.
- modified_since: (string) Filters records updated since a specified ISO 8601 date.
- page: (number) The page number for results (defaults to 1).
- per_page: (number) The quantity of projects displayed per page (defaults to 50, maximum 50).
Returns project summaries, client linkages, budget constraints, status details, and custom fields.
get_project_activities: Fetches historical logs documenting changes made to project records.
Optional Parameters:
- project_ids: (array of numbers) Limits logs to specified project entities.
- user_ids: (array of numbers) Filters activities performed by particular users.
- activity_types: (array of strings) Narrows results by action type: "status_change", "note_added", "budget_change", "date_change", or "custom_field_change".
- modified_before: (string) Filters logs updated before a specified ISO 8601 time.
- modified_since: (string) Filters logs updated since a specified ISO 8601 time.
- page: (number) Page index for pagination (defaults to 1).
- per_page: (number) Number of entries per page (defaults to 50, maximum 50).
Returns logs detailing the action taken, the responsible user, prior and new values, and precise timestamps.

Reports Tools

These utilities generate aggregate data summaries essential for performance review.

get_current_totals: Provides an immediate summary of active time entries, including daily and shift totals.
Optional Parameters:
- user_ids: (array of numbers) Filters the totals calculation for specific employees.
- group_ids: (array of numbers) Filters the totals calculation for users within designated groups.
- jobcode_ids: (array of numbers) Filters the totals calculation based on specific work classifications.
- customfield_query: (string) Filters based on custom field values using the structure: ||.
Returns real-time aggregated durations, entry start times, associated user/jobcode context, and applicable custom field values.
get_payroll: Generates a detailed report summarizing payroll data for a defined period.
Required Parameters:
- start_date: (string) The initial date defining the reporting pay period (YYYY-MM-DD).
- end_date: (string) The final date defining the reporting pay period (YYYY-MM-DD).
Optional Parameters:
- user_ids: (array of numbers) Limits the payroll data compilation to selected individuals.
- group_ids: (array of numbers) Limits the payroll data compilation to specified organizational groups.
- include_zero_time: (boolean) Determines if users with zero recorded time should appear (default is false).
Returns total time categorized by type (standard, overtime, double-time, PTO) along with daily breakdowns per user and timesheet counts.
get_payroll_by_jobcode: Generates payroll summaries aggregated according to work classifications.
Required Parameters:
- start_date: (string) The beginning date of the pay cycle (YYYY-MM-DD format).
- end_date: (string) The concluding date of the pay cycle (YYYY-MM-DD format).
Optional Parameters:
- user_ids: (array of numbers) Filters the aggregation to include only specific users.
- group_ids: (array of numbers) Filters the aggregation to include only users from specified groups.
- jobcode_ids: (array of numbers) Filters the aggregation to only certain job classifications.
- jobcode_type: (string) Filters the aggregation by time category: "regular", "pto", "paid_break", or "unpaid_break".
- include_zero_time: (boolean) Includes jobcodes with zero recorded activity (default is false).
Returns time totals grouped by jobcode, with subtotals for individual users and daily summaries for each code.
get_project_report: Produces an in-depth report detailing time allocations against defined projects.
Required Parameters:
- start_date: (string) The starting boundary for time entries (YYYY-MM-DD format).
- end_date: (string) The ending boundary for time entries (YYYY-MM-DD format).
Optional Parameters:
- user_ids: (array of numbers) Filters the report entries by user IDs.
- group_ids: (array of numbers) Filters the report entries by group affiliations.
- jobcode_ids: (array of numbers) Filters the report entries by associated jobcode IDs.
- jobcode_type: (string) Filters entries by time type: "regular", "pto", "unpaid_break", "paid_break", or "all" (default: "all").
- customfielditems: (object) Filters using a structure mapping custom field IDs to required values: {"customfield_id": ["value1", "value2"]}.
Returns total time consumption per project, broken down by user and group, showing all time entries matching the specified filters.

Additional Tools

These utilities retrieve configuration settings and system metadata.

get_custom_fields: Retrieves definitions for tracking fields configured within timecards.
Parameters:
- ids: (array of numbers) Filters by specific custom field identifiers.
- active: (string) Filters by status: "yes", "no", or "both".
- applies_to: (string) Filters by where the field is used: "timesheet", "jobcode", or "user".
- value_type: (string) Filters by data input mechanism: "managed-list" or "free-form".
- page: (number) The requested page number for results.
- limit: (number) The quantity of fields returned per page.
get_last_modified: Queries the most recent update timestamps across various system objects.
Parameters:
- types: (array of strings) Specifies object categories to check, for example: ["timesheets", "jobcodes", "users"].
get_notifications: Fetches system notifications generated by the service.
Parameters:
- page: (number) The desired page number for notification listing.
- limit: (number) The maximum number of notifications shown per page.
get_managed_clients: Retrieves information regarding clients managed through the system interface.
Parameters:
- page: (number) Specifies the page number for client retrieval.
- limit: (number) Sets the maximum number of client records per page.

Extra Details

Some original components related to project tracking contained detailed information regarding task dependencies and the ambiguity of near-completion states. In project execution, tasks often rely on preceding steps; delays in these prerequisites can halt overall progress significantly. Furthermore, estimating the remaining effort when a task is substantially finished (e.g., 90% done) is notoriously inaccurate in practice, despite mathematical consistency. This gateway provides the data necessary for external logic to model and manage these critical project uncertainties.

Conclusion

This consolidated interface streamlines complex API interactions, providing the necessary data foundation for robust workforce management and organizational oversight. By facilitating precise access to time entries, user configurations, and project structures, it supports effective coordination among team members working toward collective goals, mitigating issues related to timing and scope definition within projects.