todo-mcp-server

A minimal MCP server that gives AI agents a checklist they can initialize, track, and tick off as they work through tasks. Built for GitHub Copilot cloud agent but works with any MCP client.

Tools

| Tool | Description | |------|-------------| | todo_init | Create a checklist from a list of items (replaces existing) | | todo_list | Show all items with ✅/⬜ status and progress % | | todo_check | Mark items done by ID or text match | | todo_uncheck | Mark items not-done by ID or text match | | todo_add | Add new items to the existing checklist |

Usage with npx (no install needed)

GitHub Copilot Cloud Agent

In Settings → Copilot → Cloud agent → MCP configuration:

{
  "mcpServers": {
    "todo": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "todo-mcp-server"]
    }
  }
}

That's it. No copilot-setup-steps.yml changes needed — npx pulls and runs it on the fly.

Custom Agent (YAML)

---
name: tutorial-runner
description: "Runs through tutorial steps and tracks progress"
mcp-servers:
  todo:
    type: stdio
    command: npx
    args: ["-y", "todo-mcp-server"]
---

When working through multi-step tasks:
1. Use todo_init to create a checklist of all steps
2. After completing each step, use todo_check to mark it done
3. Use todo_list to review progress before moving on

Claude Code / VS Code / Cursor

Add to your MCP config (.claude/mcp.json, .vscode/mcp.json, etc.):

{
  "todo": {
    "command": "npx",
    "args": ["-y", "todo-mcp-server"]
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | TODO_FILE | todo-checklist.json | Path to the JSON file storing the checklist |

Example Interaction

Agent: todo_init(items: ["Install dependencies", "Configure auth", "Write tests", "Deploy"])

⬜ 1. Install dependencies
⬜ 2. Configure auth
⬜ 3. Write tests
⬜ 4. Deploy
Progress: 0/4 (0%)

Agent: todo_check(ids: [1])

✅ 1. Install dependencies
⬜ 2. Configure auth
⬜ 3. Write tests
⬜ 4. Deploy
Progress: 1/4 (25%)

Agent: todo_check(match: "auth")

✅ 1. Install dependencies
✅ 2. Configure auth
⬜ 3. Write tests
⬜ 4. Deploy
Progress: 2/4 (50%)

Publishing to npm

npm install
npm run build
npm publish

Once published, npx -y todo-mcp-server just works everywhere.

License

MIT