Introduction

This consolidated MCP server furnishes a singular interface to interact with all capabilities provided by the QuickBooks Time Application Programming Interface. It functionally merges the utilities previously distributed across four distinct components: Project Designations, Performance Metrics and Core Data, Time Record Handling, and User Administration functions. Such unification streamlines interaction for business management applications.

Application Programming Interface (API) Interaction
Resource Management Systems
Time and Attendance Tracking
Data Aggregation Methodologies
Competitive Business Performance Enhancement

Setup

To initiate operation, install the necessary package prerequisites using the following command structure:

pip install -r requirements.txt

Next, establish an environment file named .env that must contain your required QuickBooks Time authorization credential. Include the following directives within this file:

QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Claude Desktop Configuration

Configuration within the Claude Desktop environment requires specific settings adjustments for this server integration. The subsequent JSON snippet illustrates a representative setup within your configuration file:

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

Running the Server

The execution command to launch the integrated server process is provided below. The server will subsequently await JSON-RPC communication via standard input and standard output streams.

python main.py

Available Tools

JobCode Tools

get_jobcodes: Retrieves designations with sophisticated filtering capabilities.
- Basic Filters:
  - ids: (array of numbers, optional) A comma-separated list of designation identifiers.
  - name: (string, optional) Filter based on designation nomenclature, supporting leading wildcard matches (*).
  - active: (string, optional) Status filter: "yes", "no", or "both" (default is "yes").
- Type and Hierarchy Filters:
  - type: (string, optional) Filter by designation classification: "regular", "pto", "paid_break", "unpaid_break", or "all" (default is "regular").
  - parent_ids: (array of numbers, optional) Filter based on parent designation identifiers. Zero (0) selects top-level entries; negative one (-1) selects all levels.
- Additional Filters:
  - customfields: (boolean, optional) Determines if custom metadata fields are included in the response data.
  - modified_before: (string, optional) Filters records updated prior to a specified ISO 8601 timestamp.
  - modified_since: (string, optional) Filters records updated subsequent to a specified ISO 8601 timestamp.
  - page: (number) Specifies the desired results page number for retrieval.
  - limit: (number) Sets the maximum count of items returned per page (maximum allowed is 200).
get_jobcode: Retrieves a singular designation using its unique identifier.
- Required Parameters:
  - id: (number) The unique system identifier for the target designation.
get_jobcode_hierarchy: Fetches the complete structural arrangement of all designations.
- Parameters:
  - parent_ids: (array of numbers, optional) Filters results by parent identifiers (0 for root, -1 for all).
  - active: (string, optional) Filters based on current status: "yes", "no", or "both" (default is "yes").
  - type: (string, optional) Filters by designation category, defaulting to "regular".
  - customfields: (boolean, optional) Includes custom property data in the output structure.

Timesheet Tools

get_timesheets: Fetches records of time entry, supporting various selection criteria.
- Required Parameters (at least one must be present):
  - ids: (array of numbers) A list of specific time record identifiers.
  - start_date: (string) Retrieves records occurring on or following this date (format: YYYY-MM-DD).
  - modified_before: (string) Retrieves records modified before this precise ISO 8601 time.
  - modified_since: (string) Retrieves records modified after this precise ISO 8601 time.
- Optional Parameters:
  - end_date: (string) Retrieves records occurring on or preceding this date (format: YYYY-MM-DD).
  - user_ids: (array of numbers) Filters entries based on associated user identifiers.
  - group_ids: (array of numbers) Filters entries based on user group affiliations.
  - jobcode_ids: (array of numbers) Filters entries linked to specific designations (children included).
  - payroll_ids: (array of numbers) Filters entries associated with particular payroll processing identifiers.
  - on_the_clock: (string) Filters based on current active status: "yes", "no", or "both" (default is "no").
  - jobcode_type: (string) Filters by the time type recorded, defaulting to "all".
  - page: (number) Specifies the index for pagination of results.
  - limit: (number) Defines the maximum quantity of results returned per page.
get_timesheet: Retrieves one time record based on its identifier.
- Required Parameters:
  - id: (number) The unique identifier of the time record needed.
get_current_timesheets: Obtains records representing time actively being logged right now.
- Required Parameters:
  - on_the_clock: (string) This parameter must be set explicitly to "yes".
- Optional Parameters:
  - user_ids: (array of numbers) Filters active logs for designated users.
  - group_ids: (array of numbers) Filters active logs for users belonging to specified groups.
  - jobcode_ids: (array of numbers) Filters active logs associated with particular designations.
  - supplemental_data: (string) Controls the inclusion of supplementary metadata: "yes" or "no" (default is "yes").

get_users: Retrieves information for all system users, supporting various selection filters.
- User Identification Filters:
  - ids: (array of numbers, optional) Filters results to include only specified user identifiers.
  - not_ids: (array of numbers, optional) Excludes users matching these identifiers from the result set.
  - employee_numbers: (array of numbers, optional) Filters based on internal employee identification values.
  - usernames: (array of strings, optional) Filters using exact username matches.
- Group Filters:
  - group_ids: (array of numbers, optional) Limits results to users within these specified 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 system identification numbers.
  - active: (string, optional) Filters by user status: "yes", "no", or "both" (default is "yes").
- Name Filters:
  - first_name: (string, optional) Filters results by first name, supporting starting-pattern matching (*).
  - last_name: (string, optional) Filters results by last name, supporting starting-pattern matching (*).
- Time-Based Filters:
  - modified_before: (string, optional) Filters users updated before a specified ISO 8601 date-time.
  - modified_since: (string, optional) Filters users updated since a specified ISO 8601 date-time.
- Pagination:
  - page: (number, optional) Indicates the page number to retrieve (defaults to 1).
  - per_page: (number, optional) Sets the count of records per page (defaults to 50; maximum is 50).
get_user: Fetches the detailed record for a single user via their ID.
- Required Parameters:
  - id: (number) The unique system identifier for the requested user.
get_current_user: Retrieves data for the user authenticated by the current access token.
- No parameters are needed for this operation.
- The response supplies comprehensive data, including basic identification, company assignments, paid-time-off balances, security permissions, and custom metadata.
get_groups: Queries the system to retrieve all defined organizational groups.
- Optional Parameters:
  - ids: (array of numbers) Limits the retrieval to a selection of group identifiers.
  - active: (string) Filters results by group status: "yes", "no", or "both" (default is "yes").
  - manager_ids: (array of numbers) Filters groups based on their assigned managing user identifiers.
  - supplemental_data: (string) Controls inclusion of supplementary metadata: "yes" or "no" (default is "yes").
- The output includes fundamental group attributes, manager assignments, specific settings for time entries and breaks, and other contextual details.

Project Management Tools

get_projects: Retrieves a list of active or inactive projects, supporting filtering.
- Optional Parameters:
  - ids: (array of numbers) Filters results to specific project identifiers.
  - active: (string) Filters by project status: "yes", "no", or "both" (default is "yes").
  - client_id: (number) Filters based on the associated client identifier.
  - jobcode_id: (number) Filters based on a linked designation identifier.
  - modified_before: (string) Filters projects updated before a specific ISO 8601 timestamp.
  - modified_since: (string) Filters projects updated after a specific ISO 8601 timestamp.
  - page: (number) Specifies the page index for results (default is 1).
  - per_page: (number) Sets the result count per page (default is 50; maximum is 50).
- The return data covers basic project descriptions, links to clients and designations, budget allocations, operational status, and custom metadata.
get_project_activities: Fetches logs detailing changes made to project records.
- Optional Parameters:
  - project_ids: (array of numbers) Filters logs to changes within these specific projects.
  - user_ids: (array of numbers) Filters logs to actions performed by these users.
  - activity_types: (array of strings) Filters by the nature of the change, e.g., "status_change" or "budget_change".
  - modified_before: (string) Filters logs updated before a specified ISO 8601 timestamp.
  - modified_since: (string) Filters logs updated after a specified ISO 8601 timestamp.
  - page: (number) Specifies the page index for results (default is 1).
  - per_page: (number) Sets the result count per page (default is 50).
- The output details the activity type, the responsible user, the historical and current values, and the relevant time markers.

Reports Tools

get_current_totals: Provides an immediate snapshot of aggregated time, including shift and daily summaries.
- Optional Parameters:
  - user_ids: (array of numbers) Filters the aggregation to data from specific users.
  - group_ids: (array of numbers) Filters the aggregation based on user group membership.
  - jobcode_ids: (array of numbers) Filters the aggregation to specific designation time entries.
  - customfield_query: (string) Filters based on custom field values, using the format: ||.
- The response details real-time aggregated durations, initiation times for active entries, linking information for jobcodes and users, and recorded custom field data.
get_payroll: Generates a standard payroll summary report for a specified interval.
- Required Parameters:
  - start_date: (string) Defines the beginning date of the payroll period (YYYY-MM-DD).
  - end_date: (string) Defines the concluding date of the payroll period (YYYY-MM-DD).
- Optional Parameters:
  - user_ids: (array of numbers) Filters the report to include only specified users.
  - group_ids: (array of numbers) Filters the report based on user group affiliations.
  - include_zero_time: (boolean) If true, users without recorded time are included (defaults to false).
- The report summarizes total time categorized by type (standard, overtime, PTO) and presents daily breakdowns per user, along with associated time record counts.
get_payroll_by_jobcode: Generates a payroll report where time data is aggregated according to job designation.
- Required Parameters:
  - start_date: (string) Sets the payroll period start date using the YYYY-MM-DD format.
  - end_date: (string) Sets the payroll period end date using the YYYY-MM-DD format.
- Optional Parameters:
  - user_ids: (array of numbers) Limits the payroll calculation to selected users.
  - group_ids: (array of numbers) Filters the payroll calculation by user group.
  - jobcode_ids: (array of numbers) Focuses the calculation on specific designations.
  - jobcode_type: (string) Filters the aggregation by time type: "regular", "pto", "paid_break", or "unpaid_break".
  - include_zero_time: (boolean) If true, designations with zero logged time are included (defaults to false).
- This function returns total time sums categorized by job designation, with sub-breakdowns showing user contributions within each designation and daily summaries per designation.
get_project_report: Produces an in-depth report detailing time allocations against specific projects.
- Required Parameters:
  - start_date: (string) The initial date for the report range, formatted as YYYY-MM-DD.
  - end_date: (string) The final date for the report range, formatted as YYYY-MM-DD.
- Optional Parameters:
  - user_ids: (array of numbers) Filters the report entries based on designated users.
  - group_ids: (array of numbers) Filters entries based on user groups.
  - jobcode_ids: (array of numbers) Filters entries associated with specified designations.
  - jobcode_type: (string) Filters the included time entries by their type, defaulting to "all".
  - customfielditems: (object) Allows filtering using custom field data in a key-value structure: {"field_id": ["value1", "value2"]}.
- The output delivers total time figures per project, followed by detailed breakdowns segmented by user and group, reflecting only the time entries meeting the specified criteria.

Additional Tools

get_custom_fields: Retrieves definitions for custom tracking fields configured within the time tracking system.
- Parameters:
  - ids: (array of numbers) Filters by specific custom field identifiers.
  - active: (string) Filters by definition status: "yes", "no", or "both".
  - applies_to: (string) Filters by the entity the field is applied to: "timesheet", "jobcode", or "user".
  - value_type: (string) Filters by how values are stored: "managed-list" or "free-form".
  - page: (number) Page number selection for results.
  - limit: (number) Maximum quantity of definitions returned per page.
get_last_modified: Checks the most recent update timestamps across various tracked object types.
- Parameters:
  - types: (array of strings) A list specifying the object categories to query (e.g., ["timesheets", "jobcodes", "users"]).
get_notifications: Accesses system alerts and notifications.
- Parameters:
  - page: (number) The requested page number for notification listing.
  - limit: (number) The count of notifications displayed per page.
get_managed_clients: Retrieves the list of clients managed through the system.
- Parameters:
  - page: (number) The requested page number for client listing.
  - limit: (number) The count of clients displayed per page.

Extra Details

This consolidated gateway abstracts the complexity of managing multiple disparate API endpoints, which is typical for effective business management tools. By unifying access points, the system supports the core organizational need to cope with changing operational demands efficiently. For instance, many parameters across these calls, such as ISO 8601 timestamps, rely on standardized data formats common in enterprise systems to ensure data integrity during transfer and processing.

Conclusion

This server provides a robust mechanism for interacting with QuickBooks Time data, offering granular control over time records, user assignments, and project structures. This centralization supports better organizational responsiveness to market conditions by simplifying data retrieval and management workflows, which is a fundamental goal of modern business applications.

License

This software is released under the terms of the MIT License; refer to the LICENSE file for complete specifics.

Contributing

Community involvement in enhancing this software is genuinely appreciated. Kindly submit contributions via a standard Pull Request. Since the initial development leveraged significant artificial intelligence augmentation, peer review and refinements from human expertise are particularly valuable for ongoing maintenance and quality assurance.