mcp

Get a single Teamwork Chat conversation by ID.

Get the current authenticated Teamwork Chat user, including identity, counts (unread conversations/messages, mentions), and settings.

Get the 1:1 direct-message conversation with a person, creating it if it does not exist yet. Returns the conversation (use its id with send_message). Use list_people to find user_id. The authenticated user cannot be the target: naming your own user id is rejected.

List Teamwork Chat conversations the current user is a member of.

List messages within a Teamwork Chat conversation. Requires conversation_id.

List people in the Teamwork Chat installation. Useful for resolving names to user IDs.

Send a direct message to a person, resolving (or creating) the 1:1 conversation automatically. Requires user_id and body. Use list_people to find user_id. The authenticated user cannot be the recipient: naming your own user id is rejected and nothing is sent, so report a summary in the conversation instead of messaging yourself in chat.

Send a message to a Teamwork Chat conversation. Requires conversation_id and body.

Create Desk company.

Create customer.

Upload file. Attach the returned ID to tickets or messages.

Create a new help doc article.

Create ticket priority.

Create ticket status.

Create Desk tag.

Create ticket.

Create ticket type.

Get Desk company (customer organization).

Get customer.

Get a help doc article by ID.

Get a help doc site (knowledge base) by ID, including its subdomain, branding and article counts.

Get inbox.

Get ticket priority.

Get ticket status.

Get Desk tag.

Get ticket.

Get ticket type.

Get support agent.

Link a Teamwork Projects task to a Desk ticket, so the ticket shows the work tracked by that task.

List Desk companies. Filter by name, domains, or kind.

List customers. Filter by company or email.

List help doc sites (knowledge bases). Filter by name or subdomain. Use this to discover the site ID required by the help doc article tools.

List inboxes. Filter by name or email.

List ticket priorities. Filter by name or color.

List ticket statuses. Filter by name, color, or code.

List Desk tags. Filter by name, color, or inbox.

List ticket types. Filter by name or inbox.

List support agents. For customers, use twdesk-list_customers.

Reply to a ticket. Use threadType=note for internal agent notes.

Search help doc articles. Filter by search term, status, site, or category.

Search tickets. Filter by inbox, customer, company, tag, status, priority, user, or creation date range. Name the attributes you need in fields: a ticket returned whole carries every activity, message, file and timelog identifier it has, and a full page of those is large enough to be truncated in transit. The record and page totals saturate at 10000: a search reporting exactly that many has 10000 or more, and asking for a page past the 10000th result is rejected rather than answered empty, so narrow the filters instead of paging deeper.

Unlink a Teamwork Projects task from a Desk ticket. The task and the ticket themselves are kept.

Update Desk company.

Update customer.

Update an existing help doc article.

Update ticket priority.

Update ticket status.

Update Desk tag.

Update ticket.

Update ticket type.

Store an uploaded file in a project's files area, where people find it outside any one task or comment. Upload it first with twprojects-create_upload_url, then pass the reference here. Returns a numeric file ID which, unlike a reference, survives being used: pass it in attachment_file_ids on twprojects-create_task or twprojects-update_task to attach the same file to as many tasks as needed. Attaching a reference to a task, comment or message already files it here, so use this tool to store a file on its own, to describe or categorise it, or when it has to reach more than one place.

Add a user to a project.

Clone/copy an existing project or instantiate one from a template.

Mark task complete.

Stop a timer permanently and convert it to a timelog. Use pause_timer to pause without converting.

Exact milestone count for any filter set: one call, one number, no rows. Use for "how many milestones" questions (per project, per tag, matching a term) instead of paging twprojects-list_milestones to count rows. Use twprojects-list_milestones when the rows are needed.

Exact project count for any filter set: one call, one number, no rows. Use for "how many projects" questions (mine, late, per category, per tag, per company, per owner, matching a term) instead of paging twprojects-list_projects to count rows. Use twprojects-list_projects when the rows are needed.

Exact task count for any filter set: one call, one number, no rows. Use for "how many" questions (totals, late, per person, per project, per tag, completed in a window) instead of paging twprojects-list_tasks to count rows. Note due_before excludes tasks with no due date, unless a related milestone due date matches. Use twprojects-list_tasks when the rows are needed.

Exact count of time entries for any filter set: one call, one number, no rows. This counts entries, not hours — for logged, billable or billed time totals use twprojects-summarize_timelogs. Use for "how many time entries" questions (per project, per task, per person, in a date window) instead of paging twprojects-list_timelogs to count rows.

Commit a user's time to a project over a date range (a scheduler allocation). This is planned time, a separate plane from task estimates and logged time.

Create comment on a task, milestone, notebook, file, or link.

Create company (aka client).

Create custom field.

Set a custom field value on a task, project or company. The custom field must already exist and be applicable to the target entity.

Create a new custom item type (e.g. Contracts, Leads, Deals) on a project. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Add a field (column) to a custom item type. Field types include text, number, dropdown, multiselect, checkbox, url, user, date, time and datetime. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Create a record (row) on a custom item type. For example, add a Contract on the Contracts type. Pass field values by name; the tool resolves names to the API's internal IDs. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Upload short text you are generating yourself, such as a plan, a spec or a CSV, so it can be attached to a task, comment or message. Returns a single-use reference; pass it in attachment_refs on twprojects-create_task, twprojects-update_task, twprojects-create_comment or twprojects-create_message. Content is sent inline as base64, which means you have to emit the whole file as text, so use twprojects-create_upload_url instead for anything that already exists as a file — it hands back a URL to send the bytes to directly, and is the only safe option for a document that must stay byte-for-byte identical.

Create job role.

Create link.

Create message in a project.

Create message reply.

Create milestone in a project.

Create notebook in a project.

Create project.

Create project category.

Create project template.

Create skill.

Create tag.

Create task in a tasklist.

Create tasklist in a project.

Create team.

Create timelog entry against a project or task.

Create and start a timer.

Reserve an upload for a file and get back a short-lived URL to send its bytes to, plus a single-use reference. Use this for any file that already exists — a PDF, an image, a signed document — because the bytes go straight from you to storage and are never read into the conversation. Send the file with the returned method and URL, setting exactly the headers returned and no authorization of your own. Then pass the reference in attachment_refs on twprojects-create_task, twprojects-update_task, twprojects-create_comment or twprojects-create_message. Prefer twprojects-create_file only for short text you are generating yourself.

Create user.

Create workflow.

Create workflow stage.

Read the content of a file stored in Teamwork.com: text files come back as text, images as an image, and anything else as a base64 resource with its media type. Files over 10 MB are refused; point the user at the file's downloadURL from twprojects-get_file instead. The file ID is in a task's or message reply's attachments and a comment's files (each {id, type: "files"}), or comes from twprojects-list_files.

Get an allocation. linkedTaskEstimatedTime counts each linked task whole, and a task can sit behind more than one allocation, so it must not be summed across allocations.

Get comment.

Get company (aka client).

Get custom field.

Get a single custom field value from a task, project or company.

Get a custom item type with its fields and sections inline, so you can see its schema before creating or updating records. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Get a single field on a custom item type. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Get a single record. Field values come back keyed by display name with dropdown values translated to their human-readable labels. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Get a file's details: name, size, uploader, version history, the tasks, messages and comments it is attached to, and its downloadURL. The downloadURL needs the caller's own Teamwork session, so hand it to a signed-in user rather than fetching it; use twprojects-download_file to read the content here.

Get job role. The people assigned to the role come back under users, and those holding it as their primary role under primaryUsers; both are references, resolved to names under included.users.

Get link.

Get message.

Get message reply.

Get milestone.

Get notebook.

Get project.

Get project category.

Get skill.

Get tag.

Get task.

Get tasklist.

Get team.

Get timelog.

Get timer.

Get user.

Get the currently authenticated user.

Get workflow.

Get workflow stage.

Link a project to a workflow so its tasks track through workflow stages.

Link one task to an allocation, showing what task work sits behind the committed time. The task and the allocation must be in the same project. This adds a single link and leaves the allocation's other links alone, unlike linked_task_ids on twprojects-update_allocation, which replaces the whole set.

List recent activity events. Scope by project_id or omit for site-wide.

List scheduler allocations — who is committed to which project, and when. ALWAYS pass start_date and end_date: with neither set the endpoint returns only today through 30 days from today, and says nothing about having narrowed the range, so an unbounded call silently answers a question about a wider period with one month of data. Allocations are planned time and a separate plane from task estimates and logged time; the two are not summed. linkedTaskEstimatedTime counts each linked task whole and must not be summed across allocations.

List events from a calendar, including time-blocking events that link a calendar slot to a Teamwork project, task or timelog. Omit calendar_id to read the calling user's own calendar. Use twprojects-list_calendars to name a different one; the calendar of type 'blocked_time' holds the account's time-blocking events.

List calendars. Calendars hold events such as meetings, out-of-office periods and time-blocking entries; the calendar of type 'blocked_time' holds the account's time-blocking events.

List comments. Scope by one of task_id, milestone_id, notebook_id, link_id, or file_version_id; omit all for site-wide. Comment bodies are truncated at 500 characters and marked where they are cut; use twprojects-get_comment for the full text.

List companies (aka clients).

List the custom field values of a task, project or company.

List custom fields.

List fields on a custom item type. Each entry includes the twId you need when writing record values. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

List records on a custom item type. Returns each record with field values keyed by display name. Use the section_ids filter to scope to a specific section. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

List the custom item types defined on a project. Returns each type's id, display name and labels — call get_custom_item to see a type's fields and sections. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

List the files in a project's files area, or across every project when no project_id is given. Files attached to tasks, comments and messages live there too, so task_id answers "what is attached to this task". Deleted files are left out unless show_deleted is true. Each row carries a downloadURL that needs the caller's own Teamwork session; use twprojects-download_file to read the content here.

List supported company (aka client) industries.

List job roles. A verbose row carries the people assigned to the role under users, and those holding it as their primary role under primaryUsers; both are references, resolved to names under included.users.

List links.

List replies under a message thread. Filter by message_ids or project_ids.

List project messages (top-level posts). Use twprojects-list_message_replies for thread replies.

List milestones. Scope by project_id or omit for site-wide. Completed milestones are included by default; pass show_completed false to see only the outstanding ones. Use due_after and due_before to bound the deadline instead of listing everything and filtering afterwards.

List notebooks.

Lists top-level project budgets. Filters: project_ids, status.Returns only budgeted projects (diff with twprojects-list_projects for budgetless).Filter server-side via project_ids when known. 1-based page pagination (pageOffset = page - 1)

List project categories.

List project templates.

List project updates: the Markdown text on a project's dashboard and the health it reports. Nothing else returns either — a project row carries no health, and the activity log holds a preview of the text, not the text. Newest first. Only each project's current update is returned unless active_only is false, so an unfiltered call is not the whole history. Rows carry text (Markdown, in full, emoji codes already converted to characters), health (0 not set, 1 bad, 2 ok, 3 good), healthLabel (the name this installation gives that rating — read it, never build one from health) and color (hex, empty when the health is not set). The author and the project are bare IDs, sideloaded under included when verbose is true. Keep a response small with fields and page_size; verbose=false drops the text and returns the ratings.

List projects with structured filters (membership, progress state, health, category, tag, company, owner). For "my projects" pass user_ids with the ID from twprojects-get_user_me, or only_starred. For projects that have slipped pass project_statuses=["late"] — a project row carries no late flag, so this filter is the only way to ask.

List skills.

List tags.

List tasklist budgets nested under a project budget. Requires project_budget_id.

List tasklists. Scope by project_id or omit for site-wide.

List tasks with structured filters (tasklist_id, project_id, or site-wide). For keyword search use search. Completed tasks and tasks in completed tasklists are excluded unless show_completed is true, so an empty result may mean the matching work is already done rather than missing. Ask for "late", "overdue", "due today", "started" or "upcoming" work through date_filter, and leave people out through exclude_assignee_user_ids, rather than reading rows and filtering them yourself.

List teams. Scope by company_id or project_id, or omit for site-wide.

List timelogs. Scope by project_id or task_id, or omit for site-wide.

List timers.

List users. Scope by project_id or filter by type (account/collaborator/contact).

List workflow stages.

List workflows.

Move one or more tasks to a workflow stage.

Move tasks and all their subtasks to another tasklist, preserving the parent/child structure. Subtasks move with their parent automatically, so only the topmost task of each subtree needs to be listed. A task whose parent is not part of the move is detached from it, becoming a top-level task in the destination.

Pause a running timer; can be resumed later. Use complete_timer to stop permanently.

Restore a deleted allocation. Find the ID first with twprojects-list_allocations and show_deleted set, since a deleted allocation is otherwise not returned.

Resume a paused timer back to running.

Cross-entity keyword search across projects, tasks, messages, comments, users and more; restrict which entity types are searched with types. Long content fields in the sideloaded records are truncated at 500 characters and marked where they are cut; the marker names the tool that returns the full record. Completed items are excluded unless include_completed_items is true, so an empty result may mean the matching work is already done rather than missing.

Complete time totals for a date window, grouped by user, project or task (rows in groups) or by day, week or month (rows in periods). One call returns every row, in exact minutes and hours to 2 decimals. Prefer it over twprojects-list_timelogs for any total, sum or breakdown; list_timelogs is for individual entries. Minutes are authoritative, unbilledBillable = billable − billed, and rows sum to totals. One dimension per call: for hours per user per week, call once per user with user_ids. Task rows omit project-level and subtask time, so never add totals across group_by values. Period rows cover every period in order, zeros included, first and last clipped to the window; weeks follow the caller's start-of-week setting, so buckets can differ per user, and a weekend-only week with no time is dropped.

Remove the link between one task and an allocation. Only the association is removed: both the task and the allocation are left in place. This removes a single link and leaves the allocation's other links alone.

Update an allocation. Changing end_date ADDS or REMOVES committed time rather than redistributing it, because the per-day rate is what is held constant.

Update comment.

Update company (aka client).

Update custom field.

Update a custom field value on a task, project or company.

Update a custom item type's display name, description, or labels. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Update a field on a custom item type. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Update a record on a custom item type. Only the fields you supply are changed; others are left as-is. Set section_id to null to remove the record from any section. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Update job role.

Update link.

Update message.

Update message reply.

Update milestone.

Update notebook.

Update project.

Update project category.

Update skill.

Update tag.

Update task.

Update tasklist.

Update team.

Update timelog. It can also be moved to another project or task.

Update timer.

Update user.

Update workflow.

Update workflow stage.

Get task allocation across users for a date range. (workload of users)

Create space category.

Create comment on a page. Use parentId for replies.

Create page in a space.

Create space.

Create one or more Spaces tags in a single request.

Duplicate page with a new title.

Get space category.

Get page comment.

Get a space's homepage.

Get page. Returns content, metadata, tags, and revision info.

Get space.

Get Spaces tag.

List space categories.

List comments on a page. Returns top-level comments with replies.

List pages in a space as a hierarchical tree. Returns the space's open pages under `pages`; set includePrivate to also receive, under a sibling `private` key, the restricted pages the calling user has access to. Returns at most 100 pages per call by default, up to 500 with pageSize, counted across both trees. A space with more pages than that is cut in depth-first order and the response carries a `truncated` marker naming the total page count, the pageOffset that returns the next set, and twspaces-get_page for a single page in full.

List space collaborators (users and teams).

List spaces.

List Spaces tags.

Full-text search across pages. Filter by space.

Update space category.

Update page comment.

Update page. Note: content and publish changes update the published page only, not the live collaborative editor draft; if the page has an active editor draft, re-publishing from the Spaces web editor can overwrite these changes (known Spaces limitation).

Update space.

Update Spaces tag.