get_asset_faces
Retrieves all detected faces in a photo with their person assignments. Use to see who is in a photo or get face IDs for reassignment.
Instructions
Get all detected faces in a photo with their person assignments. Use this to see who is in a specific photo or to find face IDs for reassign_face. Read-only.
Args:
asset_id: The asset's UUID.
Returns: JSON array of face detections (each with face_id, person_id, person_name, bounding box).Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| asset_id | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/immich_mcp_server/server.py:987-998 (handler)MCP tool handler that calls ImmichClient.get_asset_faces(asset_id) and returns JSON-serialized face detections.
@mcp.tool() async def get_asset_faces(ctx: Context, asset_id: str) -> str: """Get all detected faces in a photo with their person assignments. Use this to see who is in a specific photo or to find face IDs for reassign_face. Read-only. Args: asset_id: The asset's UUID. Returns: JSON array of face detections (each with face_id, person_id, person_name, bounding box). """ result = await _client(ctx).get_asset_faces(asset_id) return json.dumps(result, default=str) - Helper method that sends GET /faces with asset_id param to the Immich REST API and returns the list of detected faces.
async def get_asset_faces(self, asset_id: str) -> list[dict]: """Get all detected faces for an asset.""" return await self._request("GET", "/faces", params={"id": asset_id})