QuickBooks Time MCP Server (V2 Update)

This is a combined MCP server that provides access to all QuickBooks Time API functionality through a single interface. It combines the functionality of four separate servers:

1. JobCode Tools
2. Reports & Core Tools
3. Timesheet Tools
4. User Tools

I would LOVE help improving this project! Just glad to be able to give something back finally!

This entire project was developed and published using artificial intelligence (Anthropic, OpenAI, Llama/META), as I personally cannot write much code without assistance. While every effort has been made to ensure quality and functionality, there may be imperfections or areas for improvement. I welcome any feedback, corrections, or suggestions from the community.

1. Install dependencies:

pip install -r requirements.txt

2. Create a .env file with your QuickBooks Time access token:

QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Claude Desktop Configuration

To use this server with Claude Desktop, you'll need to configure it in your Claude Desktop settings. Here's an example configuration:

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

Available Tools

JobCode Tools

• get_jobcodes: Get jobcodes with advanced filtering options

  • Basic Filters:
    • ids: (array of numbers, optional) Comma separated list of jobcode IDs
    • name: (string, optional) Filter by jobcode name, supports wildcard (*) matching from string start
    • active: (string, optional) Filter by status: "yes", "no", "both" (default: "yes")
  • Type and Hierarchy Filters:
    • type: (string, optional) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all" (default: "regular")
    • parent_ids: (array of numbers, optional) Filter by parent jobcode IDs. Special values: 0 (top-level only), -1 (all levels)
  • Additional Filters:
    • customfields: (boolean, optional) Include custom fields in response
    • modified_before: (string, optional) Filter by modification date (ISO 8601 format)
    • modified_since: (string, optional) Filter by modification date (ISO 8601 format)
    • page: (number) Page number for pagination
    • limit: (number) Results per page (max 200)

• get_jobcode: Get a specific jobcode by ID

  • Required Parameters:
    • id: (number) The ID of the jobcode to retrieve

• get_jobcode_hierarchy: Get complete jobcode hierarchy structure

  • Parameters:
    • parent_ids: (array of numbers, optional) Filter by parent IDs. Values: 0 (top-level), -1 (all), or specific IDs
    • active: (string, optional) Filter by status: "yes", "no", "both" (default: "yes")
    • type: (string, optional) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all" (default: "regular")
    • customfields: (boolean, optional) Include custom fields in response

Timesheet Tools

• get_timesheets: Get timesheets with filtering

  • Required Parameters (at least one):
    • ids: (array of numbers) Comma separated list of timesheet IDs
    • start_date: (string) Returns timesheets on or after this date (YYYY-MM-DD)
    • modified_before: (string) Returns timesheets modified before this time (ISO 8601)
    • modified_since: (string) Returns timesheets modified since this time (ISO 8601)
  • Optional Parameters:
    • end_date: (string) Returns timesheets on or before this date (YYYY-MM-DD)
    • user_ids: (array of numbers) Filter by specific user IDs
    • group_ids: (array of numbers) Filter by specific group IDs
    • jobcode_ids: (array of numbers) Filter by specific jobcode IDs (includes children)
    • payroll_ids: (array of numbers) Filter by specific payroll IDs
    • on_the_clock: (string) Filter by current working status: "yes", "no", "both" (default: "no")
    • jobcode_type: (string) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all" (default: "all")
    • page: (number) Page number
    • limit: (number) Results per page

• get_timesheet: Get a specific timesheet by ID

  • Required Parameters:
    • id: (number) The ID of the timesheet to retrieve

• get_current_timesheets: Get currently active timesheets

  • Required Parameters:
    • on_the_clock: (string) Must be set to "yes"
  • Optional Parameters:
    • user_ids: (array of numbers) Filter active timesheets for specific users
    • group_ids: (array of numbers) Filter active timesheets for users in specific groups
    • jobcode_ids: (array of numbers) Filter active timesheets for specific jobcodes
    • supplemental_data: (string) Include supplemental data: "yes", "no" (default: "yes")

User Tools

• get_users: Get all users with filtering

  • User Identification Filters:
    • ids: (array of numbers, optional) Filter by specific user IDs
    • not_ids: (array of numbers, optional) Exclude specific user IDs
    • employee_numbers: (array of numbers, optional) Filter by employee numbers
    • usernames: (array of strings, optional) Filter by specific usernames
  • Group Filters:
    • group_ids: (array of numbers, optional) Filter by group membership
    • not_group_ids: (array of numbers, optional) Exclude users from specific groups
  • Status and Identification Filters:
    • payroll_ids: (array of strings, optional) Filter by payroll identification numbers
    • active: (string, optional) Filter by status: "yes", "no", "both" (default: "yes")
  • Name Filters:
    • first_name: (string, optional) Filter by first name (supports wildcards *)
    • last_name: (string, optional) Filter by last name (supports wildcards *)
  • Time-Based Filters:
    • modified_before: (string, optional) Filter by modification date (ISO 8601)
    • modified_since: (string, optional) Filter by modification date (ISO 8601)
  • Pagination:
    • page: (number, optional) Page number (default: 1)
    • per_page: (number, optional) Results per page (default: 50, max: 50)

• get_user: Get a specific user by ID

  • Required Parameters:
    • id: (number) The ID of the user to retrieve

• get_current_user: Get currently authenticated user

  • No parameters required
  • Returns detailed user information including:
    • Basic profile information
    • Company details
    • PTO balances
    • Permissions
    • Custom fields

• get_groups: Get all groups from QuickBooks Time

  • Optional Parameters:
    • ids: (array of numbers) Filter by specific group IDs
    • active: (string) Filter by status: "yes", "no", "both" (default: "yes")
    • manager_ids: (array of numbers) Filter groups by manager user IDs
    • supplemental_data: (string) Include supplemental data: "yes", "no" (default: "yes")
  • Returns group information including:
    • Basic group details
    • Manager assignments
    • Timesheet settings
    • Time entry settings
    • Break settings

Project Management Tools

• get_projects: Get projects with filtering

  • Optional Parameters:
    • ids: (array of numbers) Filter by specific project IDs
    • active: (string) Filter by status: "yes", "no", "both" (default: "yes")
    • client_id: (number) Filter by client ID
    • jobcode_id: (number) Filter by associated jobcode ID
    • modified_before: (string) Filter by modification date (ISO 8601)
    • modified_since: (string) Filter by modification date (ISO 8601)
    • page: (number) Page number (default: 1)
    • per_page: (number) Results per page (default: 50, max: 50)
  • Returns project information including:
    • Basic project details
    • Client and jobcode associations
    • Budget information
    • Dates and status
    • Custom fields

• get_project_activities: Get project activity logs

  • Optional Parameters:
    • project_ids: (array of numbers) Filter activities to specific projects
    • user_ids: (array of numbers) Filter activities by specific users
    • activity_types: (array of strings) Filter by activity types: "status_change", "note_added", "budget_change", "date_change", "custom_field_change"
    • modified_before: (string) Filter by modification date (ISO 8601)
    • modified_since: (string) Filter by modification date (ISO 8601)
    • page: (number) Page number (default: 1)
    • per_page: (number) Results per page (default: 50, max: 50)
  • Returns activity information including:
    • Activity type and details
    • User who made the change
    • Old and new values
    • Timestamps

Reports Tools

• get_current_totals: Get current totals snapshot including shift and day totals

  • Optional Parameters:
    • user_ids: (array of numbers) Filter totals to specific users
    • group_ids: (array of numbers) Filter totals for users in specific groups
    • jobcode_ids: (array of numbers) Filter totals for specific jobcodes
    • customfield_query: (string) Filter by custom field values in format: <customfield_id>||
  • Returns:
    • Real-time totals for active time entries
    • Duration and start times
    • Associated jobcode and user information
    • Custom field values

• get_payroll: Get payroll report

  • Required Parameters:
    • start_date: (string) Start of pay period (YYYY-MM-DD)
    • end_date: (string) End of pay period (YYYY-MM-DD)
  • Optional Parameters:
    • user_ids: (array of numbers) Filter payroll for specific users
    • group_ids: (array of numbers) Filter payroll for users in specific groups
    • include_zero_time: (boolean) Include users with no time entries (default: false)
  • Returns:
    • Total time by type (regular, overtime, double-time, PTO)
    • Daily breakdowns per user
    • Timesheet counts

• get_payroll_by_jobcode: Get payroll report grouped by jobcode

  • Required Parameters:
    • start_date: (string) Start of pay period (YYYY-MM-DD)
    • end_date: (string) End of pay period (YYYY-MM-DD)
  • Optional Parameters:
    • user_ids: (array of numbers) Filter payroll for specific users
    • group_ids: (array of numbers) Filter payroll for users in specific groups
    • jobcode_ids: (array of numbers) Filter payroll for specific jobcodes
    • jobcode_type: (string) Filter by type: "regular", "pto", "paid_break", "unpaid_break"
    • include_zero_time: (boolean) Include jobcodes with no time entries (default: false)
  • Returns:
    • Time totals by jobcode
    • Breakdowns by user within each jobcode
    • Daily totals per jobcode

• get_project_report: Get detailed project report with time entries

  • Required Parameters:
    • start_date: (string) Start date in YYYY-MM-DD format
    • end_date: (string) End date in YYYY-MM-DD format
  • Optional Parameters:
    • user_ids: (array of numbers) Filter time entries by specific users
    • group_ids: (array of numbers) Filter time entries by specific groups
    • jobcode_ids: (array of numbers) Filter time entries by specific jobcodes
    • jobcode_type: (string) Filter by type: "regular", "pto", "unpaid_break", "paid_break", "all" (default: "all")
    • customfielditems: (object) Filter by custom field values in format: {"customfield_id": ["value1", "value2"]}
  • Returns:
    • Project time totals
    • Breakdowns by user and group
    • Filtered time entries based on criteria

Additional Tools

• get_custom_fields: Get custom tracking fields configured on timecards

  • Parameters:
    • ids: (array of numbers) Filter by specific custom field IDs
    • active: (string) Filter by status: "yes", "no", "both"
    • applies_to: (string) Filter by application type: "timesheet", "jobcode", "user"
    • value_type: (string) Filter by value type: "managed-list", "free-form"
    • page: (number) Page number
    • limit: (number) Results per page

• get_last_modified: Get last modified timestamps for objects

  • Parameters:
    • types: (array of strings) Types of objects to check (e.g., ["timesheets", "jobcodes", "users"])

• get_notifications: Get notifications

  • Parameters:
    • page: (number) Page number
    • limit: (number) Results per page

• get_managed_clients: Get managed clients

  • Parameters:
    • page: (number) Page number
    • limit: (number) Results per page

Running the Server

python main.py

The server will start and listen for JSON-RPC requests on stdin/stdout.

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Given that this project was developed with AI assistance, community input is especially valuable for improving and maintaining the codebase.

Support

For issues and feature requests, please use the GitHub issues page or contact me directly at github.com/aallsbury.