*MCP › Referencia › Alquileres › Proyectos*

# Listar proyectos

> Devuelve los proyectos que agrupan pedidos y trabajo, paginados por cursor.

Aislamiento heredado de la cuenta principal: una cuenta de facturación ve también los proyectos de su cuenta principal.

HERRAMIENTA `filmo_projects_list` · `projects:read` · 120/min · Anotación del servidor: Solo lectura · Anotación del servidor: Idempotente

## Argumentos

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `limit` | integer | No | Tamaño de página (1-500). Por defecto es 50. = `50` |
| `cursor` | string | No | Cursor opaco de la página que se devuelve. Pasa el valor de `pagination.nextCursor` de la respuesta anterior; trátalo como opaco. |
| `q` | string | No | Búsqueda de texto libre en el nombre y la referencia externa. |
| `sort` | string | No | Orden: hasta 3 campos separados por comas, cada uno con un "-" inicial para descendente (p. ej. "-updatedAt,name"). Campos ordenables: createdAt, updatedAt, name, projectNumber, startDate, endDate, status. Por defecto, "-createdAt". Los empates se resuelven por id, así que el orden es estable entre páginas, y un cursor queda ligado al orden con el que se emitió. |
| `status` | string | No | Filtra por estado del proyecto: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled o archived (estado heredado presente en datos antiguos). `draft`, `budgeted`, `confirmed`, `in_progress`, `invoiced`, `completed`, `cancelled`, `archived` |
| `contactId` | string | No | Filtra por identificador del contacto del proyecto. |
| `projectTypeId` | string | No | Filtra por identificador del tipo de proyecto. |
| `archived` | boolean | No | Filtra por archivado: "true" lista SOLO los proyectos archivados; "false" (o ausente) los excluye del listado. |
| `includeTotal` | boolean | No | Ponlo en true para incluir `pagination.total`, el número de resultados que coinciden con los filtros en todas las páginas. Desactivado por defecto. = `false` |
| `dateFilters` | object | No | Filtros de fecha por campo. Una fecha sin hora (YYYY-MM-DD) se lee en la zona horaria del negocio; un instante ISO 8601 con desplazamiento se aplica tal cual con gte, lte, gt y lt, mientras que on lo amplía al día completo del negocio que lo contiene. Campos: created, updated. |
| `dateFilters.created` | object | No |  |
| `dateFilters.created.gte` | string | No | Desde este día o instante, inclusive. |
| `dateFilters.created.lte` | string | No | Hasta este día o instante, inclusive. |
| `dateFilters.created.gt` | string | No | Estrictamente posterior; una fecha sin hora significa después del final de ese día. |
| `dateFilters.created.lt` | string | No | Estrictamente anterior; una fecha sin hora significa antes del inicio de ese día. |
| `dateFilters.created.on` | string | No | Exactamente ese día; un instante significa toda la jornada del negocio que lo contiene. |
| `dateFilters.updated` | object | No |  |
| `dateFilters.updated.gte` | string | No | Desde este día o instante, inclusive. |
| `dateFilters.updated.lte` | string | No | Hasta este día o instante, inclusive. |
| `dateFilters.updated.gt` | string | No | Estrictamente posterior; una fecha sin hora significa después del final de ese día. |
| `dateFilters.updated.lt` | string | No | Estrictamente anterior; una fecha sin hora significa antes del inicio de ese día. |
| `dateFilters.updated.on` | string | No | Exactamente ese día; un instante significa toda la jornada del negocio que lo contiene. |

## Resultado

En un éxito el resultado lleva `structuredContent` con `data` y `meta`. Estos son los atributos de `data`.

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `id` | string | Identificador único del proyecto. |
| `projectNumber` | string | Número de proyecto legible; null si no está numerado. |
| `name` | string | Nombre del proyecto. |
| `color` | string | Color asociado al proyecto (para la interfaz); null si no tiene. |
| `externalReference` | string | Referencia externa del proyecto (por ejemplo, del sistema del cliente); null si no consta. |
| `projectTypeId` | string | Identificador del tipo de proyecto; null si el proyecto no tiene tipo. |
| `projectType` | object | Referencia compacta al tipo de proyecto; null si no hay. |
| `projectType.id` | string | Identificador único del tipo de proyecto. |
| `projectType.name` | string | Nombre del tipo de proyecto. |
| `projectType.color` | string | Color asociado al tipo de proyecto (para la interfaz); null si no tiene. |
| `contact` | object | Referencia compacta al contacto del proyecto; null si no hay. |
| `contact.id` | string | Identificador único del contacto. |
| `contact.name` | string | Nombre del contacto. |
| `location` | object | Ubicación del proyecto; sus campos internos son null cuando no se han registrado. |
| `location.name` | string | Nombre del lugar o ubicación; null si no está registrado. |
| `location.address` | string | Dirección de la ubicación; null si no consta. |
| `location.city` | string | Ciudad de la ubicación; null si no consta. |
| `location.postalCode` | string | Código postal de la ubicación; null si no se ha registrado. |
| `location.province` | string | Provincia o región de la ubicación; null si no se ha registrado. |
| `location.country` | string | País de la ubicación; null si no consta. |
| `location.lat` | number | Latitud de la ubicación; null si no está registrada. |
| `location.lng` | number | Longitud de la ubicación; null si no está registrada. |
| `startDate` | string<date-time> | Fecha de inicio del proyecto en ISO 8601 con desplazamiento. |
| `endDate` | string<date-time> | Fecha de fin del proyecto en ISO 8601 con desplazamiento. |
| `status` | string | Estado del proyecto: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled o archived. `archived` es un estado HEREDADO que aparece en datos antiguos; el estado archivado actual se expresa mediante el booleano `archived` de este mismo DTO. `draft`, `budgeted`, `confirmed`, `in_progress`, `invoiced`, `completed`, `cancelled`, `archived` |
| `archived` | boolean | Si el proyecto está archivado. |
| `orderIds` | string[] | Identificadores de los pedidos del proyecto. El detalle de los pedidos se obtiene en [`GET /api/v1/orders`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/list-orders)?projectId=. |
| `totalOrders` | integer | Número total de pedidos del proyecto (igual a orderIds.length). |
| `tags` | object[] | Etiquetas adjuntas al proyecto, con su identificador y nombre. |
| `tags.id` | string | Identificador único de la etiqueta. |
| `tags.name` | string | Nombre de la etiqueta. |
| `customFields` | object<string, any> | Valores de los campos personalizados por identificador de campo personalizado; las definiciones están en `/api/v1/custom-fields`. |
| `source` | string | Origen desde el que se creó el proyecto; null si no consta. |
| `createdAt` | string<date-time> | Fecha de creación en ISO 8601 con desplazamiento. |
| `updatedAt` | string<date-time> | Fecha de la última actualización en ISO 8601 con desplazamiento. |

*Llamada · filmo_projects_list*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_projects_list",
    "arguments": {
      "limit": 20
    }
  }
}
```

*Resultado (generado desde el esquema)*

```json
{
  "structuredContent": {
    "data": [
      {
        "id": "id_8f2a1c",
        "projectNumber": "<projectNumber>",
        "name": "Example",
        "color": "<color>",
        "externalReference": "<externalReference>",
        "projectTypeId": "proj_8f2a1c",
        "projectType": {
          "id": "id_8f2a1c",
          "name": "Example",
          "color": "<color>"
        },
        "contact": {
          "id": "id_8f2a1c",
          "name": "Example"
        },
        "location": {
          "name": "Example",
          "address": "<address>",
          "city": "<city>",
          "postalCode": "<postalCode>",
          "province": "<province>",
          "country": "ES",
          "lat": 1,
          "lng": 1
        },
        "startDate": "2026-09-01T08:00:00Z",
        "endDate": "2026-09-01T08:00:00Z",
        "status": "draft",
        "archived": true,
        "orderIds": [
          "orde_8f2a1c"
        ],
        "totalOrders": 1,
        "tags": [
          {
            "id": "id_8f2a1c",
            "name": "Example"
          }
        ],
        "customFields": {
          "key": "<key>"
        },
        "source": "<source>",
        "createdAt": "2026-09-01T08:00:00Z",
        "updatedAt": "2026-09-01T08:00:00Z"
      }
    ],
    "pagination": {
      "nextCursor": "eyJvIjo1MH0",
      "hasMore": true,
      "total": 1
    },
    "meta": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## Prompts de ejemplo

*Prompt*

```text
Lista los proyectos activos y el número de pedidos de cada uno.
```

## La misma operación por REST

Esta herramienta ejecuta [`GET /api/v1/projects`](https://docs.filmo.io/es/rest-api/endpoint-reference/projects/list-projects).

---

URL canónica: https://docs.filmo.io/es/mcp/tools/projects/filmo-projects-list  
Última actualización: 2026-10-25