Todoist

Se integra con la API de Todoist para gestionar tus tareas y proyectos.

GitHub
1

Documentación

Servidor MCP de Todoist

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona integración con la API de Todoist para asistentes de IA.

Descripción General

El Servidor MCP de Todoist permite a los asistentes de IA interactuar con Todoist, permitiéndoles gestionar tareas y proyectos en nombre de los usuarios. Este servidor implementa el Protocolo de Contexto de Modelo (MCP), proporcionando una interfaz estandarizada para que los sistemas de IA accedan a la funcionalidad de Todoist.

Características

  • Gestión de Tareas

    • Obtener reglas de filtrado y ejemplos para el filtrado de tareas
    • Obtener tareas con opciones de filtrado
    • Obtener detalles de tareas
    • Crear nuevas tareas
    • Actualizar tareas existentes
    • Marcar tareas como completadas
    • Eliminar tareas

  • Gestión de Proyectos

    • Obtener todos los proyectos
    • Obtener detalles de proyectos

Instalación

Requisitos Previos

  • Go 1.21 o posterior (para compilar desde el código fuente)
  • Docker (para instalación mediante Docker)
  • Token de API de Todoist

Compilación desde el Código Fuente

  1. Clonar el repositorio:
git clone https://github.com/naotama2002/todoist-go-mcp-server.git
cd todoist-go-mcp-server
  1. Instalar dependencias:
go mod download
  1. Compilar el binario:
make build

Usando Docker

También puedes ejecutar todoist-mcp-server usando Docker, lo que proporciona un entorno consistente y un despliegue más sencillo.

Descargar desde GitHub Container Registry

# Pull the latest image
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:latest

# Or pull a specific version
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:{TAG}

Compilar localmente

# Build the Docker image
docker build -t todoist-mcp-server .

Configuración

Configura tu token de API de Todoist:

Crea un archivo .envrc en el directorio raíz con el siguiente contenido:

export TODOIST_API_TOKEN=your_todoist_api_token

Si estás usando direnv, ejecuta:

direnv allow

Alternativamente, puedes establecer la variable de entorno directamente:

export TODOIST_API_TOKEN=your_todoist_api_token

Uso

Ejecutando el Servidor

Uso del Binario

Modo HTTP

Ejecuta el servidor en modo HTTP:

go run cmd/todoist-mcp-server/main.go --mode http --addr :8080

O usando el binario compilado:

./build/todoist-mcp-server --mode http --addr :8080
Modo de Entrada/Salida Estándar

Ejecuta el servidor en modo stdio para integración con clientes MCP:

go run cmd/todoist-mcp-server/main.go --mode stdio

O usando el binario compilado:

./build/todoist-mcp-server --mode stdio

Uso con Docker

Modo HTTP
# Basic usage with Docker
docker run --rm -it -p 8080:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :8080

# With custom port
docker run --rm -it -p 3000:3000 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :3000

# Using locally built image
docker run --rm -it -p 8080:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  todoist-mcp-server --mode http --addr :8080
Modo de Entrada/Salida Estándar
# For stdio mode (used with MCP clients)
docker run --rm -i -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

# Using locally built image
docker run --rm -i -e TODOIST_API_TOKEN=your_todoist_api_token \
  todoist-mcp-server --mode stdio

Opciones de Línea de Comandos

El servidor admite las siguientes opciones de línea de comandos:

  • --mode <mode>: Modo del servidor, ya sea 'http' o 'stdio' (predeterminado: "http")
    • http: Ejecutar como servidor HTTP
    • stdio: Ejecutar usando entrada/salida estándar para comunicación MCP
  • --addr <address>: Dirección para escuchar en modo HTTP (predeterminado: ":8080")
  • --token <token>: Token de API de Todoist (también se puede configurar mediante la variable de entorno TODOIST_API_TOKEN)

Ejemplos:

# Run HTTP server on port 3000
go run cmd/todoist-mcp-server/main.go --mode http --addr :3000

# Run with a specific Todoist API token
go run cmd/todoist-mcp-server/main.go --mode http --token your_todoist_api_token

# Run in stdio mode
go run cmd/todoist-mcp-server/main.go --mode stdio

Probando con el Cliente MCP

Puedes probar el servidor usando el cliente de prueba incluido:

go run cmd/test-mcp-client/main.go

Herramientas Disponibles

Gestión de Tareas

todoist_get_task_filter_rules

Obtener reglas de filtrado y ejemplos para filtros de tareas de Todoist. Esta herramienta ayuda a traducir consultas en lenguaje natural a la sintaxis de filtros de Todoist para la herramienta todoist_get_tasks.

Parámetros: Ninguno

Ejemplo de respuesta (formato Markdown):

# Introduction to Filters

Filters in Todoist are custom views that display tasks based on specific criteria. You can filter tasks by name, date, project, label, priority, creation date, and more.

## Creating Filters

1. Select "Filters & Labels" in the sidebar
2. Click the add icon next to Filters
3. Enter a name for your filter and change its color (optional)
4. Enter your filter query
5. Click "Add" to save your filter

## Filter Symbols

| Symbol | Meaning | Example |
|--------|---------|--------|
| \| | OR | today \| overdue |
| & | AND | today & p1 |
| ! | NOT | !subtask |
| () | Priority processing | (today \| overdue) & #work |

## Advanced Queries

### Keyword-Based Filters

| Description | Query |
|-------------|-------|
| Tasks containing "meeting" | search: meeting |
| Tasks containing "meeting" scheduled for today | search: meeting & today |

### Date-Based Filters

| Description | Query |
|-------------|-------|
| Tasks for a specific date | date: jan 3 |
| Tasks before a specific date | before: may 5 |
| Tasks with no date | no date |

## Useful Filter Examples

| Description | Query |
|-------------|-------|
| Overdue or today's tasks in "Work" project | (today \| overdue) & #work |
| Tasks with no date | no date |
| Tasks with @waiting label in the next 7 days | 7 days & @waiting |


#### `todoist_get_tasks`

Get a list of tasks with filtering options.

Parameters:
- `projectId` (string, optional): Filter tasks by project ID
- `filter` (string, optional): Todoist filter query using the Todoist filter syntax

Example:
```json
{
  "projectId": "2203306141",
  "filter": "today"
}

todoist_get_task

Obtener detalles de una tarea específica.

Parámetros:

  • id (cadena, obligatorio): El identificador único de la tarea

Ejemplo:

{
  "id": "2995104339"
}

todoist_create_task

Crear una nueva tarea.

Parámetros:

  • content (cadena, obligatorio): El contenido de la tarea
  • description (cadena, opcional): Descripción detallada o notas para la tarea
  • projectId (cadena, opcional): ID del proyecto al que asignar la tarea
  • parentId (cadena, opcional): ID de la tarea padre para crear subtareas
  • order (entero, opcional): Valor de orden para posicionar la tarea
  • priority (entero, opcional): Prioridad de la tarea: 1 (normal), 2 (media), 3 (alta), 4 (urgente)
  • dueString (cadena, opcional): Fecha de vencimiento en lenguaje natural, p. ej., 'hoy', 'mañana'
  • dueDate (cadena, opcional): Fecha de vencimiento en formato AAAA-MM-DD
  • dueDatetime (cadena, opcional): Fecha y hora de vencimiento en formato RFC3339

Ejemplo:

{
  "content": "Buy groceries",
  "description": "Need to buy milk, eggs, and bread",
  "projectId": "2203306141",
  "priority": 2,
  "dueString": "tomorrow at 10am"
}

todoist_update_task

Actualizar una tarea existente.

Parámetros:

  • id (cadena, obligatorio): El identificador único de la tarea a actualizar
  • content (cadena, opcional): El nuevo contenido de la tarea
  • description (cadena, opcional): Descripción detallada o notas para la tarea
  • priority (entero, opcional): Prioridad de la tarea: 1 (normal), 2 (media), 3 (alta), 4 (urgente)
  • dueString (cadena, opcional): Fecha de vencimiento en lenguaje natural
  • dueDate (cadena, opcional): Fecha de vencimiento en formato AAAA-MM-DD
  • dueDatetime (cadena, opcional): Fecha y hora de vencimiento en formato RFC3339

Ejemplo:

{
  "id": "2995104339",
  "content": "Buy groceries and household items",
  "priority": 1
}

todoist_close_task

Marcar una tarea como completada.

Parámetros:

  • id (cadena, obligatorio): El identificador único de la tarea a marcar como completada

Ejemplo:

{
  "id": "2995104339"
}

todoist_delete_task

Eliminar una tarea.

Parámetros:

  • id (cadena, obligatorio): El identificador único de la tarea a eliminar

Ejemplo:

{
  "id": "2995104339"
}

Gestión de Proyectos

todoist_get_projects

Obtener una lista de todos los proyectos.

Parámetros: Ninguno

todoist_get_project

Obtener detalles de un proyecto específico.

Parámetros:

  • id (cadena, obligatorio): El identificador único del proyecto

Ejemplo:

{
  "id": "2203306141"
}

Integración con Claude Desktop

Para usar el Servidor MCP de Todoist con Claude Desktop, debes agregarlo a la configuración de Claude Desktop.

Descargar desde GitHub Releases

La forma más fácil de comenzar es descargar un binario precompilado desde la página de GitHub Releases:

  1. Ve a la página de Releases y descarga la última versión para tu plataforma:

    • Linux: todoist-mcp-server_Linux_x86_64.tar.gz o todoist-mcp-server_Linux_arm64.tar.gz
    • macOS: todoist-mcp-server_Darwin_x86_64.tar.gz o todoist-mcp-server_Darwin_arm64.tar.gz
    • Windows: todoist-mcp-server_Windows_x86_64.zip

  2. Extrae el archivo para obtener el binario todoist-mcp-server:

    # For Linux/macOS
tar -xzf todoist-mcp-server_*_*.tar.gz

# For Windows
# Extract the zip file using Windows Explorer or a tool like 7-Zip

  3. Haz que el binario sea ejecutable (solo Linux/macOS):

    chmod +x todoist-mcp-server

  4. Opcionalmente, mueve el binario a una ubicación en tu PATH:

    # Linux/macOS
sudo mv todoist-mcp-server /usr/local/bin/

# Windows
# Move the .exe file to a location in your PATH

Compilar desde el código fuente

Alternativamente, puedes compilar el binario desde el código fuente:

# Build the binary
make build

Configuración

Agrega el Servidor MCP de Todoist a tu configuración de Claude Desktop:

Modo HTTP

  1. Ejecuta el Servidor MCP de Todoist en modo HTTP:
todoist-mcp-server --mode http --addr :8080
  1. Agrega la siguiente configuración a la configuración de Claude Desktop:
{
  "name": "Todoist",
  "description": "Manage Todoist tasks and projects",
  "endpoint": "http://localhost:8080",
  "tools": [
    {
      "name": "todoist_get_task_filter_rules",
      "description": "Get filter rules and examples for Todoist task filters"
    },
    {
      "name": "todoist_get_tasks",
      "description": "Get a list of tasks with filtering options"
    },
    {
      "name": "todoist_get_task",
      "description": "Get details of a specific task"
    },
    {
      "name": "todoist_create_task",
      "description": "Create a new task"
    },
    {
      "name": "todoist_update_task",
      "description": "Update an existing task"
    },
    {
      "name": "todoist_close_task",
      "description": "Mark a task as completed"
    },
    {
      "name": "todoist_delete_task",
      "description": "Delete a task"
    },
    {
      "name": "todoist_get_projects",
      "description": "Get a list of all projects"
    },
    {
      "name": "todoist_get_project",
      "description": "Get details of a specific project"
    }
  ]
}

Modo Stdio

Usando Binario

Claude Desktop / Cline, Roo Cline / Windsurf

{
  "mcpServers": {
    "todoist": {
      "command": "/path/to/todoist-mcp-server",
      "args": ["--mode", "stdio"],
      "env": {
        "TODOIST_API_TOKEN": "<YOUR_TODOIST_API_TOKEN>"
      }
    }
  }
}

VSCode

{
  "mcp": {
    "servers": {
      "todoist": {
        "command": "/path/to/todoist-mcp-server",
        "args": ["--mode", "stdio"],
        "env": {
          "TODOIST_API_TOKEN": "<YOUR_TODOIST_API_TOKEN>"
        }
      }
    }
  }
}
Usando Docker

Claude Desktop / Cline, Roo Cline / Windsurf

{
  "mcpServers": {
    "todoist": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TODOIST_API_TOKEN=<YOUR_TODOIST_API_TOKEN>",
        "ghcr.io/naotama2002/todoist-go-mcp-server:latest",
        "--mode",
        "stdio"
      ]
    }
  }
}

VSCode

{
  "mcp": {
    "servers": {
      "todoist": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e",
          "TODOIST_API_TOKEN=<YOUR_TODOIST_API_TOKEN>",
          "ghcr.io/naotama2002/todoist-go-mcp-server:latest",
          "--mode",
          "stdio"
        ]
      }
    }
  }
}

Reemplaza /path/to/todoist-mcp-server con la ruta real al binario y <YOUR_TODOIST_API_TOKEN> con tu token de API de Todoist.

  1. En Claude Desktop, ve a Configuración > Herramientas > Agregar Herramienta, y pega la configuración JSON apropiada.

  2. Guarda la configuración y reinicia Claude Desktop si es necesario.

Ahora puedes pedirle a Claude que gestione tus tareas y proyectos de Todoist usando lenguaje natural.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Solución de Problemas

Problemas con Docker

Puerto Ya en Uso

Si obtienes un error de "puerto ya en uso", detén el servicio en conflicto o usa un puerto diferente:

# Use a different port
docker run --rm -it -p 3335:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :8080

Problemas de Red con Clientes MCP

Si los clientes MCP no pueden conectarse al contenedor Docker, intenta usar redes de host:

# Use host networking mode
docker run --rm -i --net=host -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

Problemas con Variables de Entorno

Asegúrate de que tu token de API de Todoist esté configurado correctamente:

# Check if the token is set correctly
docker run --rm -i -e TODOIST_API_TOKEN=your_actual_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

Limpiar Datos de Autenticación

Si tienes problemas con la autenticación, verifica tu token de API de Todoist:

  1. Ve a Integraciones de Todoist
  2. Copia tu token de API
  3. Asegúrate de que esté configurado correctamente en tu entorno

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

Agradecimientos

Desarrollo

Estructura del Proyecto

todoist-go-mcp-server/
├── cmd/
│   ├── test-client/        # Test client for the Todoist API
│   ├── test-mcp-client/    # Test client for the MCP server
│   └── todoist-mcp-server/ # Main MCP server application
├── docs/                   # Documentation
├── pkg/
│   ├── log/                # Logging utilities
│   ├── todoist/            # Todoist API client and tools
│   └── toolsets/           # MCP toolset definitions
└── todo/                   # Implementation plans and notes

Ejecutando Pruebas

make test