FocusBox MCP — referencia de herramientas

URL del conector: https://focusbox.io/mcp/api. Consulta /mcp para la configuración.

list_today

Devuelve las tareas del usuario programadas para hoy (solo las incompletas).

Argumentos

Ninguno.

Devuelve

Array de { taskId, name, durationSeconds, projectId }.

Ejemplo de respuesta

[
  { "taskId": "abc", "name": "Write spec", "durationSeconds": 1500, "projectId": "mytasks" }
]

next_task

Devuelve una sola tarea por la que empezar, elegida según lo que cabe en el tiempo disponible antes del próximo evento del calendario, lo que ha quedado pendiente de días anteriores y lo que es lo bastante pequeño para empezar. Incluye el motivo, dos alternativas y un enlace para empezar.

Argumentos

availableMinutes (1-480, opcional).

Devuelve

{ task, alternatives, freeWindowMinutes, busyNow, message }.

Ejemplo de respuesta

{
  "task": {
    "taskId": "abc", "name": "Finish pricing page", "projectId": "work",
    "estimateMinutes": 35, "source": "rollover",
    "reason": "Carried over from 2 days ago; fits the 47 min you have before your next meeting.",
    "startUrl": "https://focusbox.io/now?id=work&taskId=abc"
  },
  "alternatives": [],
  "freeWindowMinutes": 47, "busyNow": false,
  "message": "Start here: Finish pricing page (35 min)."
}

get_streams

Lista los proyectos de FocusBox del usuario (contenedores de tareas; llamados "streams" en la API por motivos históricos). Se excluyen los proyectos archivados y los buckets today/mytasks.

Argumentos

Ninguno.

Devuelve

Array de { streamId, name }.

add_task

Añade una nueva tarea a un proyecto o la programa para hoy. La duración por defecto es de 25 minutos.

Argumentos

Devuelve

{ taskId, streamId, name, durationSeconds }.

update_task

Actualiza uno o varios campos de una tarea existente: name, durationSeconds o dueDate.

Argumentos

Devuelve

{ taskId, streamId, name, durationSeconds, dueDate }.

delete_task

Elimina una tarea de forma permanente. Es idempotente: borrar una tarea ya eliminada no se considera un error.

Argumentos

Devuelve

{ taskId, streamId, deleted, reason? }.

complete_task

Marca una tarea de FocusBox como completada.

Argumentos

Devuelve

{ taskId, streamId, completed: true }.

get_insights_30d

Resumen agregado de las tareas completadas por el usuario en los últimos 30 días.

Argumentos

Ninguno.

Devuelve

{ totalTasks, totalFocusMinutes, topStreams[{streamId, name, tasks}, days: 30 }].

Autenticación

OAuth (recomendado para Claude)

Claude Desktop y la web de claude.ai completan el flujo de OAuth automáticamente. No hace falta gestionar API keys.

Bearer (Cursor, Inspector, clientes personalizados)

Obtén tu API key en /account/api-keys (empieza por apikey_). Envíala como Authorization: Bearer apikey_xxx en cada petición.

Límites de uso

300 llamadas a herramientas cada 2 minutos por API key. 60 sondeos sin autenticar cada 2 minutos por IP.

Preguntas frecuentes