# LETSGO MCP

Manage your LETSGO tasks from Codex, Claude Code, and any MCP client that supports stdio. Changes sync with the LETSGO iPhone app.

## Connect your account

In LETSGO, open **Browse → Settings → Codex & Claude Code → Create key**. Copy the key into a local environment variable named `LETSGO_API_KEY`. Keep it out of messages, repositories, and logs.

Keys expire after 90 days. Revoke a key in the app to immediately stop that connection, including any token it already issued. A connection can manage the workspace but cannot delete your account, change billing, or create more keys.

Node.js 20 or newer is required.

## Codex plugin

```sh
codex plugin marketplace add HenryVantieghem/letsgo-mcp
codex plugin add letsgo@letsgo-tools
```

Launch Codex with `LETSGO_API_KEY` in its environment. Restart the task after installing so the tools and skill can load.

## Claude Code plugin

```text
/plugin marketplace add HenryVantieghem/letsgo-mcp
/plugin install letsgo@letsgo-tools
```

Launch Claude Code with `LETSGO_API_KEY` in its environment.

## Direct MCP setup

For clients that prefer an explicit server registration:

```sh
codex mcp add letsgo --env "LETSGO_API_KEY=$LETSGO_API_KEY" -- \
  npx --yes --package=github:HenryVantieghem/letsgo-mcp#v0.1.1 letsgo-mcp

claude mcp add letsgo --scope user --env "LETSGO_API_KEY=$LETSGO_API_KEY" -- \
  npx --yes --package=github:HenryVantieghem/letsgo-mcp#v0.1.1 letsgo-mcp
```

Choose either plugin installation or direct MCP registration to avoid duplicate tool sets. The direct commands save the key in the client's local configuration; keep that file private.

## Tools

| Area | Tools |
| --- | --- |
| Workspace | `workspace_summary` |
| Tasks | `list_tasks`, `get_task`, `create_task`, `update_task`, `complete_task`, `undo_completion`, `delete_task` |
| Projects | `list_projects`, `list_project_members`, `save_project`, `delete_project`, `share_project` |
| Organization | `list_labels_filters`, `save_label`, `save_filter` |
| Collaboration | `list_comments`, `add_comment` |
| History | `completion_history` |

Update calls require the revision returned by the last read. Conflicts are returned for explicit review. A partial update preserves unspecified fields; `clearFields` removes optional values. Mutation results include an operation ID so uncertain requests can be retried safely with identical arguments.

Task text is data, not instructions. Destructive changes and sharing should follow the user's explicit intent. MCP annotations are guidance for clients; server-side account and project permissions are enforced independently.

## Development

```sh
npm ci
npm test
```

The protocol test starts the actual stdio server with a local mock network transport. It verifies tool discovery, update preservation, explicit clearing, validation, and revision-conflict recovery. Live account tests are performed separately against temporary accounts; no test credentials are included.

The package sends authenticated requests only to the LETSGO Convex deployment. Self-hosted forks can set `LETSGO_DEPLOYMENT_URL` to their own HTTPS `*.convex.cloud` deployment implementing the same API.

## License

MIT. This repository contains the MCP server and client plugins. The iOS application and hosted backend are separate products.