QuickBooks Time MCP Server (Combined)

by MCP-Mirror

298 downloads Not rated yet
GitHub

About

A combined MCP server that provides unified access to the QuickBooks Time API through a single interface. It merges four separate servers (JobCode Tools, Reports & Core Tools, Timesheet Tools, and User Tools) and is intended for developers and users who need to interact…

Explore

- Retrieve jobcodes with advanced filtering and hierarchy
- Fetch timesheets, including currently active ones
- Access user, group, and project management data
- Generate payroll, project, and current totals reports
- Query custom fields, notifications, and managed clients
- Paginated results and date‑range filtering on most endpoints

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name QuickBooks Time MCP Server (Combined)
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

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

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

python main.py

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

get_jobcodes

Get jobcodes with advanced filtering options

ids

(array of numbers) Filter by specific jobcode IDs

parent_ids

(array of numbers) Filter by parent jobcode IDs

name

(string) Filter by name (use * as wildcard)

type

(string) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all"

active

(string) Filter by status: "yes", "no", "both"

customfields

(boolean) Include custom field data

modified_before

(string) Return items modified before this date

modified_since

(string) Return items modified after this date

supplemental_data

(string) Include supplemental data: "yes", "no"

page

(number) Page number for pagination

limit

(number) Results per page (max 200)

get_jobcode

Get a specific jobcode by ID

id

(number) The ID of the jobcode to retrieve

get_jobcode_hierarchy

Get complete jobcode hierarchy structure

get_timesheets

Get timesheets with filtering

get_timesheet

Get a specific timesheet by ID

get_current_timesheets

Get currently active timesheets

get_users

Get all users with filtering

get_user

Get a specific user by ID

get_current_user

Get currently authenticated user

get_groups

Get all groups from QuickBooks Time

get_projects

Get projects with filtering

get_project_activities

Get project activities

get_current_totals

Get current totals snapshot including shift and day totals

get_payroll

Get payroll report

start_date

(string) Start date in YYYY-MM-DD format

end_date

(string) End date in YYYY-MM-DD format

get_payroll_by_jobcode

Get payroll report grouped by jobcode

get_project_report

Get detailed project report with time entries

jobcode_ids

(array of numbers) Filter by specific jobcode IDs

user_ids

(array of numbers) Filter by specific user IDs

group_ids

(array of numbers) Filter by specific group IDs

jobcode_type

(string) Filter by type: "regular", "pto", "unpaid_break", "paid_break", "all"

customfielditems

(object) Filter by custom field items

get_custom_fields

Get custom tracking fields configured on timecards

get_last_modified

Get last modified timestamps for objects

types

(array of strings) Types of objects to check

get_notifications

Get notifications

get_managed_clients

Get managed clients

- get_jobcodes: Get jobcodes with advanced filtering options
- Parameters:
- ids: (array of numbers) Filter by specific jobcode IDs
- parent_ids: (array of numbers) Filter by parent jobcode IDs
- name: (string) Filter by name (use as wildcard)
- type: (string) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all"
- active: (string) Filter by status: "yes", "no", "both"
- customfields: (boolean) Include custom field data
- modified_before: (string) Return items modified before this date
- modified_since: (string) Return items modified after this date
- supplemental_data: (string) Include supplemental data: "yes", "no"
- 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
- Optional Parameters:
- name: (string) Filter by name (use as wildcard)
- type: (string) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all"
- active: (string) Filter by status: "yes", "no", "both"
- customfields: (boolean) Include custom field data
- supplemental_data: (string) Include supplemental data: "yes", "no"

- get_timesheets: Get timesheets with filtering
- Parameters:
- modified_before: (string) Filter by modification date
- modified_since: (string) Filter by modification date
- 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

- get_users: Get all users with filtering
- Parameters:
- modified_before: (string) Filter by modification date
- modified_since: (string) Filter by modification date
- page: (number) Page number
- limit: (number) Results per page

- 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

- get_groups: Get all groups from QuickBooks Time
- Parameters:
- page: (number) Page number
- limit: (number) Results per page

- get_projects: Get projects with filtering
- Parameters:
- modified_before: (string) Filter by modification date
- modified_since: (string) Filter by modification date
- page: (number) Page number
- limit: (number) Results per page

- get_project_activities: Get project activities
- Parameters:
- page: (number) Page number
- limit: (number) Results per page

- get_current_totals: Get current totals snapshot including shift and day totals
- Parameters:
- page: (number) Page number
- limit: (number) Results per page

- get_payroll: Get payroll report
- Required Parameters:
- start_date: (string) Start date in YYYY-MM-DD format
- end_date: (string) End date in YYYY-MM-DD format
- Optional Parameters:
- page: (number) Page number
- limit: (number) Results per page

- get_payroll_by_jobcode: Get payroll report grouped by jobcode
- Required Parameters:
- start_date: (string) Start date in YYYY-MM-DD format
- end_date: (string) End date in YYYY-MM-DD format
- Optional Parameters:
- page: (number) Page number
- limit: (number) Results per page

- 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
- jobcode_ids: (array of numbers) Filter by specific jobcode IDs
- Optional Parameters:
- user_ids: (array of numbers) Filter by specific user IDs
- group_ids: (array of numbers) Filter by specific group IDs
- jobcode_type: (string) Filter by type: "regular", "pto", "unpaid_break", "paid_break", "all"
- customfielditems: (object) Filter by custom field items

- get_custom_fields: Get custom tracking fields configured on timecards
- Parameters:
- 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

- 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

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "quickbooks time mcp server (combined)": {
            "aallsbury_qb-time-mcp-server": {
                "command": "python",
                "args": [
                    "main.py"
                ]
            }
        }
    }
}

McpServers

{
    "aallsbury_qb-time-mcp-server": {
        "command": "python",
        "args": [
            "main.py"
        ]
    }
}

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 - Parameters: - ids: (array of numbers) Filter by specific jobcode IDs - parent_ids: (array of numbers) Filter by parent jobcode IDs - name: (string) Filter by name (use as wildcard) - type: (string) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all" - active: (string) Filter by status: "yes", "no", "both" - customfields: (boolean) Include custom field data - modified_before: (string) Return items modified before this date - modified_since: (string) Return items modified after this date - supplemental_data: (string) Include supplemental data: "yes", "no" - 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
- Optional Parameters:
- name: (string) Filter by name (use as wildcard)
- type: (string) Filter by type: "regular", "pto", "paid_break", "unpaid_break", "all"
- active: (string) Filter by status: "yes", "no", "both"
- customfields: (boolean) Include custom field data
- supplemental_data: (string) Include supplemental data: "yes", "no"

Timesheet Tools

- get_timesheets: Get timesheets with filtering - Parameters: - modified_before: (string) Filter by modification date - modified_since: (string) Filter by modification date - 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

User Tools

- get_users: Get all users with filtering - Parameters: - modified_before: (string) Filter by modification date - modified_since: (string) Filter by modification date - page: (number) Page number - limit: (number) Results per page

- 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

- get_groups: Get all groups from QuickBooks Time
- Parameters:
- page: (number) Page number
- limit: (number) Results per page

Project Management Tools

- get_projects: Get projects with filtering - Parameters: - modified_before: (string) Filter by modification date - modified_since: (string) Filter by modification date - page: (number) Page number - limit: (number) Results per page

- get_project_activities: Get project activities
- Parameters:
- page: (number) Page number
- limit: (number) Results per page

Reports Tools

- get_current_totals: Get current totals snapshot including shift and day totals - Parameters: - page: (number) Page number - limit: (number) Results per page

- get_payroll: Get payroll report
- Required Parameters:
- start_date: (string) Start date in YYYY-MM-DD format
- end_date: (string) End date in YYYY-MM-DD format
- Optional Parameters:
- page: (number) Page number
- limit: (number) Results per page

- get_payroll_by_jobcode: Get payroll report grouped by jobcode
- Required Parameters:
- start_date: (string) Start date in YYYY-MM-DD format
- end_date: (string) End date in YYYY-MM-DD format
- Optional Parameters:
- page: (number) Page number
- limit: (number) Results per page

- 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
- jobcode_ids: (array of numbers) Filter by specific jobcode IDs
- Optional Parameters:
- user_ids: (array of numbers) Filter by specific user IDs
- group_ids: (array of numbers) Filter by specific group IDs
- jobcode_type: (string) Filter by type: "regular", "pto", "unpaid_break", "paid_break", "all"
- customfielditems: (object) Filter by custom field items

Additional Tools

- get_custom_fields: Get custom tracking fields configured on timecards - Parameters: - 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

- 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.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

More like this

Similar MCP servers you might find useful

Browse category

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

— 88.2k 954.3k dl
Productivity

Github SSE

The GitHub MCP Server allows AI tools like GitHub Copilot in VS Code and Visual Studio, Claude Desktop, and others to seamlessly access live GitHub context and…

5.0 15.8k 18 dl
Developer Tools

Inbox Zero

AI personal assistant for email [Inbox Zero](https://www.getinboxzero.com)

— 11.6k 1.1k dl
Communication