Search users, groups and placeholder users
search_principalsSearch for users, groups, and placeholders by name, login, or email to obtain their IDs needed for work package assignments, watchers, time entries, and project memberships.
Instructions
Find users, groups and placeholder users, and get their ids.
This is the id-producing tool for every principal parameter in this
server: assignee/responsible on work packages, watcher ids, the
user_id of a time entry, and principal_id for create_membership
(admin-gated: hidden unless the server sets
OPENPROJECT_MCP_ADMIN_TOOLS=1). Names are never accepted where an id
is wanted — resolve here first, and never guess a numeric id.
Use it to answer "who is Grace Hopper's account", "which groups exist",
"who is a member of the demo project". Returns the standard list
envelope: items of {id, name, type, email?, login?, status?} plus
pagination{total,page,page_size,has_more} and notes.
Pitfalls. email, login and status are only returned for user
principals the authenticated account may see — a null email means "not
visible to you", not "no email". Group principals can hold memberships
and be assigned work, so filter by type when you specifically need a
person. Matching is substring-based, so a short query matches broadly;
prefer the full name or the login. member_of_project filters by
membership, not by whether the person ever touched the project.
Cross-references: get_user for one user's full detail;
list_memberships for who holds which roles in a project;
create_membership to grant access; list_roles for the role ids that
grant needs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| type | No | Restrict to one kind of principal. 'user' = people who log in, 'group' = user groups (assignable and grantable as a unit), 'placeholder' = licence-free stand-ins. Omit to search all three. | |
| query | No | Free text matched against name, login and email (substring, case-insensitive). Omit it to page through every visible principal. | |
| status | No | Restrict to an account status. 'active' is the usual filter when looking for someone to assign work to; 'locked' accounts keep old assignments but take no new ones. Groups and placeholder users have no status and are excluded when this is set. | |
| page_size | No | Principals per page, 1-100. | |
| member_of_project | No | Only principals who are members of this project. Numeric project id or the URL identifier; an identifier costs one extra lookup. Use it before assigning work — a user who is not a member usually cannot be assigned. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |