list_people
List all recognized people (face clusters) in the library. Use this to browse who appears, view thumbnails, and find person IDs for further actions.
Instructions
List all recognized people (face clusters) in the library. Use this to browse who appears in the photo library or find a person's ID. For searching by name, use search_people instead. Read-only.
Args:
page: Page number, starting from 1 (default 1).
size: Results per page (default 50).
with_hidden: Include people marked as hidden (default false).
Returns: JSON with total count, page, and people array (each with id, name, thumbnailPath, photoCount).Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| size | No | ||
| with_hidden | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/immich_mcp_server/server.py:862-880 (handler)MCP tool handler for 'list_people'. Decorated with @mcp.tool(), calls _client(ctx).list_people() and returns JSON with total, page, and people array.
@mcp.tool() async def list_people( ctx: Context, page: int = 1, size: int = 50, with_hidden: bool = False ) -> str: """List all recognized people (face clusters) in the library. Use this to browse who appears in the photo library or find a person's ID. For searching by name, use search_people instead. Read-only. Args: page: Page number, starting from 1 (default 1). size: Results per page (default 50). with_hidden: Include people marked as hidden (default false). Returns: JSON with total count, page, and people array (each with id, name, thumbnailPath, photoCount). """ result = await _client(ctx).list_people(page=page, size=size, with_hidden=with_hidden) people = result.get("people", []) total = result.get("total", len(people)) return json.dumps({"total": total, "page": page, "people": people}, default=str) - Function signature defines input schema: page (int=1), size (int=50), with_hidden (bool=False).
@mcp.tool() async def list_people( ctx: Context, page: int = 1, size: int = 50, with_hidden: bool = False ) -> str: - src/immich_mcp_server/server.py:862-863 (registration)Registered as MCP tool via @mcp.tool() decorator on the list_people function.
@mcp.tool() async def list_people( - Client-side helper method that calls GET /people with pagination params (page, size, withHidden). Called by the MCP tool handler.
async def list_people( self, page: int = 1, size: int = 50, with_hidden: bool = False ) -> dict: """List all people (paginated).""" params = {"page": str(page), "size": str(size), "withHidden": str(with_hidden).lower()} return await self._request("GET", "/people", params=params)