byob-todos-mcp

MCP server for managing BYOB todos via your own S3 bucket. Lets AI agents (Claude Code, Claude Desktop, Cursor, etc.) read and act on every BYOB entity that has an LLM affordance: tasks, recurring series, tags, weekly/monthly/yearly goals, mantras, and vision-board images.

Tracks BYOB 3.0.0 schema.

Setup

1. Install

npm install -g byob-todos-mcp

Or run directly with npx:

npx byob-todos-mcp

2. Configure your MCP client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "byob-todos": {
      "command": "npx",
      "args": ["byob-todos-mcp"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
        "AWS_REGION": "us-east-1",
        "BYOB_BUCKET_NAME": "your-bucket-name"
      }
    }
  }
}

Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "byob-todos": {
      "command": "npx",
      "args": ["byob-todos-mcp"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
        "AWS_REGION": "us-east-1",
        "BYOB_BUCKET_NAME": "your-bucket-name"
      }
    }
  }
}

Available Tools

Tasks

| Tool | Description | |------|-------------| | get_tasks | Get tasks for a date or date range (persisted + virtual recurring) | | create_task | Create a one-off task (supports tagIds, isImportant, duration) | | complete_task | Mark a task as completed | | uncomplete_task | Unmark a completed task | | update_task | Update title, date, sort order, tags, importance, or duration | | delete_task | Soft-delete a task | | abandon_task | Mark a task as abandoned (tri-state lifecycle) | | unabandon_task | Restore an abandoned task to pending |

Recurring Series

| Tool | Description | |------|-------------| | list_series | List recurring series | | create_series | Create a recurring series (daily/weekly/monthly) | | update_series | Update a series | | delete_series | Delete a series and its tasks | | abandon_series | Abandon a series (deactivates, preserves history) | | restore_series | Restore an abandoned series (resumes from today) |

Tags

| Tool | Description | |------|-------------| | list_tags | List tags | | create_tag | Create a tag with optional emoji | | update_tag | Update a tag | | delete_tag | Soft-delete a tag |

Goals (Weekly / Monthly / Yearly)

| Tool | Description | |------|-------------| | list_goals | List goals (filter by period; defaults to open) | | create_goal | Create a Weekly, Monthly, or Yearly goal | | update_goal | Update title, description, resolution, period, sort order, tags | | complete_goal | Mark a goal as completed | | uncomplete_goal | Unmark a completed goal | | abandon_goal | Mark a goal as abandoned | | unabandon_goal | Restore an abandoned goal | | delete_goal | Soft-delete a goal |

Mantras

| Tool | Description | |------|-------------| | list_mantras | List mantras (defaults to active, not archived/deleted) | | create_mantra | Create a mantra (with optional isStarred) | | update_mantra | Update text, starred state, or sort order | | archive_mantra | Archive a mantra (sets archivedAt) | | unarchive_mantra | Unarchive a mantra | | delete_mantra | Soft-delete a mantra |

Goal Images (vision board)

| Tool | Description | |------|-------------| | list_goal_images | List image metadata for goals (filter by goalId, kind) | | get_goal_image | Fetch a JPEG as an MCP image content block (vision models can view it) | | delete_goal_image | Soft-delete image metadata |

Note: image upload is intentionally not exposed. Add vision-board images via the in-app photo picker — pushing raw image bytes through MCP is heavy and a footgun.

Config

| Tool | Description | |------|-------------| | get_config | Get app configuration (auto-migrates v1 docs on read) | | update_config | Update abandonedModeEnabled and autoDeleteDays (always writes schema v2) |

Data Layout

The server reads and writes the same S3 bucket structure as the BYOB iOS app:

s3://your-bucket/
  byob/
    config.json
    tasks/{uuid}.json
    series/{uuid}.json
    tags/{uuid}.json
    goals/{uuid}.json
    mantras/{uuid}.json
    imagemeta/{uuid}.json   ← GoalImage metadata
    images/{uuid}.jpg       ← GoalImage bytes (separate object)

Calendar dates are stored as plain "yyyy-MM-dd" strings with no timezone. Timestamps are ISO 8601 UTC.

Config schema migration

config.json schema v1 (pre-3.0.0) had separate abandonedModeForTasks and abandonedModeForSeries flags. v2 unifies these into abandonedModeEnabled. On read, the server auto-migrates v1 docs by ORing the legacy flags. Writes always emit v2 and drop the legacy keys.

GoalImage kindRaw

Legacy "realized" is coerced to "accomplished" on read (renamed in BYOB commit f4092bd).

License

MIT