QB Time

This MCP server combines all QuickBooks Time API functionalities into a single, easy-to-use interface. You can run it locally and connect via a client to perform jobs like retrieving jobcodes, tracking timesheets, managing users and groups, and generating payroll or project reports. It’s designed to be invoked from an MCP client that communicates through standard input/output or via a local process, enabling automated workflows and integrations.

How to use

You run the MCP server locally and connect with your MCP client to call its functions. Start the server as a local process and then request data or perform actions by invoking the available tools by name with the required parameters. The server exposes a rich set of capabilities across job codes, timesheets, users, projects, and reports, so you can automate payroll, scheduling, project tracking, and data exports.

How to install

Prerequisites: You need Python installed on your machine. You also need access to a QuickBooks Time access token to authorize requests.

# Install Python dependencies
pip install -r requirements.txt

Create a configuration file that provides your QuickBooks Time access token and environment setting for development.

QB_TIME_ACCESS_TOKEN=your_quickbooks_time_access_token_here
NODE_ENV=development

Start the MCP server by running the main script directly from the project root. The server listens for JSON-RPC requests on standard I/O (stdin/stdout).

python main.py

Additional configuration and usage notes

To integrate with an MCP client such as Claude Desktop, you can configure a local stdio server that runs the server script and passes the required environment variable for authentication. The following example shows how to wire the local Python server into a client configuration using the provided command and environment variable.

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

Security and best practices

Keep your QuickBooks Time access token secret. Do not commit tokens to version control and consider using a secure secret store or environment management mechanism in production. Rotate tokens regularly and restrict the token’s scope to the minimum required permissions for your integration.

Troubleshooting tips

• Verify that Python and dependencies are installed correctly (pip install -r requirements.txt).
• Confirm QB_TIME_ACCESS_TOKEN is set in your environment or in the configuration you provide to your MCP client.
• Check that main.py is accessible at the path specified and that you are running the command from the project root or adjust the path accordingly.
• If the server starts but you do not receive responses, review the server logs for authentication errors or missing parameters and ensure your MCP client is sending the correct tool names and parameters.

Available tools

get_jobcodes

Fetch jobcodes with advanced filtering options such as ids, parent_ids, name with wildcard, type, active status, and pagination. Includes optional data like custom fields and supplemental_data.

get_jobcode

Retrieve a single jobcode by its ID.

get_jobcode_hierarchy

Get the complete jobcode hierarchy with optional filters for name, type, active status, and whether to include custom fields or supplemental data.

get_timesheets

Get timesheets with filtering options for modification date and pagination.

get_timesheet

Retrieve a specific timesheet by its ID.

get_current_timesheets

Obtain the list of currently active timesheets.

get_users

Fetch users with optional filters for modification date and pagination.

get_user

Retrieve a single user by ID.

get_current_user

Get the currently authenticated user.

get_groups

List all groups associated with QuickBooks Time with pagination.

get_projects

Fetch projects with optional modification-date filters and pagination.

get_project_activities

Retrieve project activities with pagination.

get_current_totals

Get a current totals snapshot including shift and day totals.

get_payroll

Generate a payroll report for a specified date range with optional pagination.

get_payroll_by_jobcode

Payroll report grouped by jobcode for a date range with optional pagination.

get_project_report

Detailed project report including time entries with various filters such as user_ids, group_ids, and jobcode_type.

get_custom_fields

Retrieve custom tracking fields configured on timecards, with pagination.

get_last_modified

Fetch last modified timestamps for specified object types.

get_notifications

List notifications with pagination.

get_managed_clients

List managed clients with pagination.