tsheets-mcp
Provides tools for interacting with the TSheets (QuickBooks Time) API, enabling management of time tracking, scheduling, PTO, users, jobcodes, custom fields, reports, and other resources in the Intuit TSheets platform.
Provides tools for interacting with the QuickBooks Time (formerly TSheets) API, enabling management of time tracking, scheduling, PTO, users, jobcodes, custom fields, reports, and other resources within the QuickBooks ecosystem.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tsheets-mcpshow my user info"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tsheets-mcp
MCP server for TSheets (QuickBooks Time) — Intuit's time-tracking, scheduling, and PTO platform. Exposes the full public TSheets REST API v1 as MCP tools.
Overview
Stateless HTTP service. No credentials are ever persisted — each request supplies its own access token via a header, used only for the lifetime of that single request.
Supports concurrent requests; per-request credential isolation is done via Python
contextvars, not a global/shared client instance.Entry points:
POST /mcp(MCP protocol) andGET /health(health check).Default port:
8080(configurable viaMCP_HTTP_PORT).No path-template parameters exist anywhere in the TSheets API — every identifier (
ids,user_id, etc.) is passed as a query-string parameter, even for single-resource lookups. This is a genuine API design characteristic, not a simplification made by this server.
Related MCP server: Timesheet MCP Server
Scope
85 tools across 34 categories, generated from the official TSheets API documentation source (https://github.com/tsheetsteam/api_docs, cloned and parsed directly — the docs' own Postman collection lists 71 requests across 29 folders, but the underlying markdown source documents several additional categories not present in that collection, e.g. TimeOffRequests/TimeOffRequestEntries, CustomFieldItemJobcodeFilters, Invitations).
MSPbots' own stored integration config for this vendor calls exactly 6 endpoints (Effective Settings, Jobcodes, Users, Customfielditem User Filters, Timesheets, Custom Fields — all GET, read-only). Per explicit user decision, this build covers the full public API including write operations (create/update/delete across every resource, plus the six built-in payroll/project report endpoints), not just those 6 calls — see Known Gaps for which tools mutate real data.
Source data was extracted by cloning the TSheets docs' own GitHub repository and parsing every per-endpoint Markdown/ERB partial file (source/includes/APIReference/<Category>/_*.md.erb) for its HTTP method, path, and parameter table — the same structured-extraction-then-codegen approach used for other large-API vendors in this program (ConnectSecure, Dynu, Jira Data Center, Opsgenie).
Authentication
TSheets uses a static access token obtained via the vendor's own OAuth/API-app flow (see MSPbots' internal KB article linked from its own integration config). MSPbots' own integration convention sends this token as Authorization: Bearer <accessToken>, matching TSheets' own documented format, and this server forwards it exactly that way.
HEADER 授权参数说明
Header | 类型 | 是否必填 | 默认值 | 枚举值 | 字段描述 | Example |
| string | 是 | 无 | 无 | TSheets 访问令牌,原样转发为上游 |
|
Missing the header returns 401:
{
"error": "Missing credentials",
"message": "This server requires the X-TSheets-Access-Token header",
"required_headers": ["X-TSheets-Access-Token"],
"optional_headers": []
}Environment Variables
Variable | 类型 | 是否必填 | 默认值 | 说明 |
| int | 否 |
| HTTP 监听端口 |
| string | 否 |
| HTTP 监听地址 |
| string | 否 |
| TSheets API 基础 URL |
MCP Endpoint
POST /mcp— MCP protocol (streamable HTTP transport)GET /health— health check, returns{"status": "ok", "service": "tsheets-mcp", "transport": "http"}
Tool List
Tool names are tsheets_<category>_<operation>, derived from each operation's ## Heading in the source docs (e.g. "Retrieve Timesheets" in the timesheets category → tsheets_timesheets_retrieve_timesheets). Several retrieve filter parameters are documented as "required (unless X, Y, or Z is set)" — a one-of-N requirement that can't be cleanly expressed as a single hard-required Python parameter, so those are modeled as optional and the OR-constraint is spelled out in the tool's own docstring instead. body parameters for create/update endpoints are accepted as a generic dict — TSheets' own convention wraps these in {"data": [ {...}, ... ]} (bulk create/update of up to 50 objects per call), documented per-tool.
Category | Tool | 功能 | 方法+路径 | 参数 |
current_user |
| Retrieve the Current User. | GET /current_user | 无 |
custom_field_item_filters |
| Create Item Filters. | POST /customfielditem_filters | body(必填) |
custom_field_item_filters |
| Retrieve Item Filters. | GET /customfielditem_filters | jobcode_id(可选), user_id(可选), group_id(可选), include_user_group(可选), include_jobcode_filters(可选), ids(可选), active(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
custom_field_item_filters |
| Update Item Filters. | PUT /customfielditem_filters | body(必填) |
custom_field_item_jobcode_filters |
| Retrieve Jobcode Filters. | GET /customfielditem_jobcode_filters | jobcode_ids(可选), modified_before(可选), modified_since(可选), limit(可选), page(可选) |
custom_field_item_user_filters |
| Retrieve User Filters. | GET /customfielditem_user_filters | user_id(可选), group_id(可选), include_user_group(可选), modified_before(可选), modified_since(可选), limit(可选), page(可选) |
custom_field_items |
| Create Custom Field Items. | POST /customfielditems | body(必填) |
custom_field_items |
| Retrieve Custom Field Items. | GET /customfielditems | customfield_id(必填), ids(可选), active(可选), name(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
custom_field_items |
| Update Custom Field Items. | PUT /customfielditems | body(必填) |
custom_fields |
| Create Custom Fields. | POST /customfields | body(必填) |
custom_fields |
| Retrieve Custom Fields. | GET /customfields | ids(可选), active(可选), applies_to(可选), value_type(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
custom_fields |
| Update Custom Fields. | PUT /customfields | body(必填) |
effective_settings |
| Retrieve Effective Settings. | GET /effective_settings | user_id(可选), modified_before(可选), modified_since(可选) |
estimate_items |
| Create Estimate Items. | POST /estimate_items | body(必填) |
estimate_items |
| Retrieve Estimate Items. | GET /estimate_items | ids(可选), estimate_ids(可选), active(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
estimate_items |
| Update Estimate Items. | PUT /estimate_items | body(必填) |
estimates |
| Create Estimates. | POST /estimates | body(必填) |
estimates |
| Retrieve Estimates. | GET /estimates | ids(可选), active(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
estimates |
| Update Estimates. | PUT /estimates | body(必填) |
files |
| Delete Files. | DELETE /files | ids(可选) |
files |
| Download a File. | GET /files/raw | id(必填) |
files |
| Retrieve Files. | GET /files | ids(可选), uploaded_by_user_ids(可选), linked_object_type(可选), object_ids(可选), active(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
files |
| Update Files. | PUT /files | body(必填) |
files |
| Upload Files. | POST /files | body(必填) |
geofence_configs |
| Retrieve Geofence Configs. | GET /geofence_configs | ids(可选), type(可选), type_ids(可选), enabled(可选), active(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选), by_jobcode_assignment(可选) |
geolocations |
| Create Geolocations. | POST /geolocations | body(必填) |
geolocations |
| Retrieve Geolocations. | GET /geolocations | ids(可选), modified_before(可选), modified_since(可选), user_ids(可选), group_ids(可选), supplemental_data(可选), limit(可选), page(可选) |
groups |
| Create Groups. | POST /groups | body(必填) |
groups |
| Retrieve Groups. | GET /groups | ids(可选), active(可选), manager_ids(可选), name(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
groups |
| Update Groups. | PUT /groups | body(必填) |
invitations |
| Create Invitations. | POST /invitations | body(必填) |
jobcode_assignments |
| Create Jobcode Assignments. | POST /jobcode_assignments | body(必填) |
jobcode_assignments |
| Delete Jobcode Assignments. | DELETE /jobcode_assignments | ids(可选) |
jobcode_assignments |
| Retrieve Jobcode Assignments. | GET /jobcode_assignments | user_ids(可选), type(可选), jobcode_id(可选), jobcode_parent_id(可选), active(可选), active_jobcodes(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
jobcodes |
| Create Jobcodes. | POST /jobcodes | body(必填) |
jobcodes |
| Retrieve Jobcodes. | GET /jobcodes | ids(可选), parent_ids(可选), name(可选), type(可选), active(可选), customfields(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
jobcodes |
| Update Jobcodes. | PUT /jobcodes | body(必填) |
last_modified |
| Retrieve Last Modified Timestamps. | GET /last_modified_timestamps | endpoints(可选) |
locations |
| Create Locations. | POST /locations | body(必填) |
locations |
| Retrieve Locations. | GET /locations | ids(可选), active(可选), geocoding_status(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选), by_jobcode_assignment(可选) |
locations |
| Update Locations. | PUT /locations | body(必填) |
locations_maps |
| Retrieve Locations Maps. | GET /locations_map | ids(可选), active(可选), modified_before(可选), modified_since(可选), limit(可选), page(可选), by_jobcode_assignment(可选) |
managed_clients |
| Retrieve Managed Clients. | GET /managed_clients | active(可选), limit(可选), page(可选) |
notifications |
| Create Notifications. | POST /notifications | body(必填) |
notifications |
| Delete Notifications. | DELETE /notifications | ids(必填) |
notifications |
| Retrieve Notifications. | GET /notifications | ids(可选), delivery_before(可选), delivery_after(可选), user_id(可选), msg_tracking_id(可选), limit(可选), page(可选) |
project_activities |
| Retrieve Project Activity objects. | GET /project_activities | project_id(可选), ids(可选), activity_types(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选), max_id(可选) |
project_activity_read_times |
| Retrieve Project Activity Read Times. | GET /project_activity_read_times | ids(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
project_activity_read_times |
| Update Project Activity Read Time. | POST /project_activity_read_times | body(必填) |
project_activity_replies |
| Create Project Activity Replies. | POST /project_activity_replies | body(必填) |
project_activity_replies |
| Retrieve Project Activity Replies. | GET /project_activity_replies | project_activity_id(必填), ids(可选), user_ids(可选), active(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
project_activity_replies |
| Update Project Activity Replies. | PUT /project_activity_replies | body(必填) |
project_notes |
| Create Project Notes. | POST /project_notes | body(必填) |
project_notes |
| Retrieve Project Notes. | GET /project_notes | project_id(必填), ids(可选), user_ids(可选), active(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
project_notes |
| Update Project Notes. | PUT /project_notes | body(必填) |
projects |
| Create Projects. | POST /projects | body(必填) |
projects |
| Retrieve Projects. | GET /projects | ids(可选), jobcode_ids(可选), parent_jobcode_id(可选), name(可选), active(可选), by_jobcode_assignment(可选) |
projects |
| Update Projects. | PUT /projects | body(必填) |
reminders |
| Create Reminders. | POST /reminders | body(必填) |
reminders |
| Retrieve Reminders. | GET /reminders | user_ids(必填), reminder_types(可选), modified_since(可选), supplemental_data(可选) |
reminders |
| Update Reminders. | PUT /reminders | body(必填) |
reports |
| Retrieve Current Totals Report. | POST /reports/current_totals | body(必填) |
reports |
| Retrieve Payroll by Jobcode Report. | POST /reports/payroll_by_jobcode | body(必填) |
reports |
| Retrieve Payroll Report. | POST /reports/payroll | body(必填) |
reports |
| Retrieve Project Estimate Detail Reports. | POST /reports/project_estimate_detail | body(必填) |
reports |
| Retrieve Project Estimate Reports. | POST /reports/project_estimate | body(必填) |
reports |
| Retrieve Project Report. | POST /reports/project | body(必填) |
schedule_calendars |
| Retrieve Schedule Calendars. | GET /schedule_calendars | ids(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
schedule_events |
| Create Schedule Events. | POST /schedule_events | body(必填) |
schedule_events |
| Retrieve Schedule Events. | GET /schedule_events | schedule_calendar_ids(必填), ids(可选), users_ids(可选), jobcode_ids(可选), start(可选), end(可选), active(可选), active_users(可选), draft(可选), team_events(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
schedule_events |
| Update Schedule Events. | PUT /schedule_events | body(必填) |
time_off_request_entries |
| Create Time Off Request Entries. | POST /time_off_request_entries | body(必填) |
time_off_request_entries |
| Retrieve Time Off Request Entries. | GET /time_off_request_entries | ids(可选), time_off_request_ids(可选), approver_user_ids(可选), status(可选), date(可选), start_time(可选), end_time(可选), jobcode_ids(可选), user_ids(可选), supplemental_data(可选), limit(可选), page(可选) |
time_off_request_entries |
| Update Time Off Request Entries. | PUT /time_off_request_entries | body(必填) |
time_off_requests |
| Create Time Off Requests. | POST /time_off_requests | body(必填) |
time_off_requests |
| Retrieve Time Off Requests. | GET /time_off_requests | ids(可选), user_ids(可选), supplemental_data(可选), limit(可选), page(可选) |
time_off_requests |
| Update Time Off Requests. | PUT /time_off_requests | body(必填) |
timesheets |
| Create Timesheets. | POST /timesheets | body(必填) |
timesheets |
| Delete Timesheets. | DELETE /timesheets | ids(可选) |
timesheets |
| Retrieve Timesheets. | GET /timesheets | ids(可选), start_date(可选), end_date(可选), jobcode_ids(可选), payroll_ids(可选), user_ids(可选), group_ids(可选), on_the_clock(可选), jobcode_type(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
timesheets |
| Update Timesheets. | PUT /timesheets | body(必填) |
timesheets_deleted |
| Retrieve Timesheets Deleted. | GET /timesheets_deleted | start_date(可选), end_date(可选), ids(可选), modified_since(可选), modified_before(可选), group_ids(可选), user_ids(可选), username(可选), jobcode_ids(可选), jobcode_type(可选), type(可选), order_results_by(可选), order_results_reverse(可选), page(可选), limit(可选) |
users |
| Create Users. | POST /users | body(必填) |
users |
| Retrieve Users. | GET /users | ids(可选), not_ids(可选), employee_numbers(可选), usernames(可选), group_ids(可选), not_group_ids(可选), payroll_ids(可选), active(可选), first_name(可选), last_name(可选), modified_before(可选), modified_since(可选), supplemental_data(可选), limit(可选), page(可选) |
users |
| Update Users. | PUT /users | body(必填) |
测试示例
# Health check
curl -s http://localhost:8080/health
# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
-H "X-TSheets-Access-Token: <your-tsheets-access-token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id-from-initialize>" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "tsheets_current_user_retrieve_the_current_user",
"arguments": {}
}
}'Live-verified (2026-07-30): a first test access token turned out to be expired (401 invalid_grant, confirmed identical via direct curl — see the bug note below for what that run caught). A second, freshly-issued access token was then tested end-to-end through this running server and returned real account data: tsheets_current_user_retrieve_the_current_user returned the actual current user record (name, permissions, PTO balances) plus supplemental jobcode data, and tsheets_jobcodes_retrieve_jobcodes (matching one of MSPbots' own 6 configured endpoints) returned real jobcode records. Both confirm the full request/auth/response pipeline works correctly against the live API.
Bug fixed during self-test: the initial _raise_for_status error parser assumed TSheets always nests error details as {"error": {"message": "..."}}, but TSheets actually returns an OAuth-style flat {"error": "invalid_grant", "error_description": "..."} for auth failures — calling .get() on the string "invalid_grant" crashed with 'str' object has no attribute 'get'. This was caught and fixed using the first (expired) test token, before this server was considered done.
API Reference
Overview: https://tsheetsteam.github.io/api_docs/
Source (incl. official Postman collection): https://github.com/tsheetsteam/api_docs
Known Gaps
Full API coverage was an explicit user decision, matching the pattern used for other large public APIs in this program. MSPbots itself only calls 6 read-only endpoints; every
create/update/deletetool here mutates real TSheets data (timesheets, users, jobcodes, schedule events, files, etc.) or — fortsheets_timesheets_delete_timesheetsandtsheets_files_delete_filesin particular — permanently deletes records/attached files per the vendor's own docs. Treat any such tool as destructive/irreversible and confirm with a human before invoking.One-of-N "required" filter groups are modeled as all-optional — several
Retrieveendpoints document a param as "required (unless X, Y, or Z is set)"; enforcing that as a real constraint isn't expressible in a plain function signature, so all such params are optional in the tool signature and the OR-requirement is spelled out in the docstring instead. Callers must supply at least one per the documented constraint or the live API will reject the request.bodyparameters are untyped (dict) rather than fully modeled — TSheets' own docs show per-type field variants (e.g. "Regular Timesheets" vs "Manual Timesheets" have different required fields within the samedataarray), which don't map cleanly onto fixed typed parameters; the vendor's own reference (linked above) documents the exact schema per resource.Source data comes from the docs' Markdown/ERB partials (not the API's actual OpenAPI/JSON-Schema, which TSheets doesn't publish) — the extraction was verified against the official Postman collection shipped in the same repository for cross-consistency (71 of 85 tools have a matching Postman request; the other 14 are documented-but-not-in-Postman categories like Time Off Requests).
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
- -license-quality-maintenanceProvides MCP integration for Harvest's time tracking, project management, and invoicing functionality, enabling natural language interaction with Harvest API through tools for managing clients, time entries, projects, tasks, and users.Last updated

Timesheet MCP Serverofficial
AlicenseBqualityAmaintenanceEnables natural language control of the Timesheet API for timer management, task tracking, and project management through MCP tools.Last updated50351MIT- AlicenseCqualityAmaintenanceEnables interacting with Clockify time-tracking data through natural language, providing tools to manage workspaces, projects, time entries, reports, and more via the MCP protocol.Last updated481MIT
- Alicense-qualityBmaintenanceEnables natural language time tracking and booking for WorkTracker via MCP tools, allowing users to assign time, list projects, and manage daily schedules through conversational commands.Last updatedMIT
Related MCP Connectors
Manage projects, tasks, time tracking, and team collaboration through natural language.
34 production API tools over one hosted MCP endpoint.
ClickUp MCP — wraps the ClickUp REST API v2 (BYO API key)
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MSPbotsAI/tsheets-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server