todo-tree MCP Server

Exposes your todo-tree task list as MCP tools so any MCP-compatible AI client (Claude Desktop, etc.) can read and manage your tasks. It supports both stdio transport (default) and SSE (HTTP) transport with dynamic client-side authentication.

Modes of Operation

1. SSE (HTTP) Mode with Web Portal (Recommended)

By defining the PORT environment variable, the server will boot as an HTTP server supporting Server-Sent Events (SSE). It hosts a web interface allowing non-technical users to easily log in and connect.

Setup

1. Create a .env file based on .env.example:

   PORT=3001
   TODO_TREE_API_URL=http://localhost:1337
   

2. Start the server:

   npm start
   

3. Open http://localhost:3001 in your browser.
4. Log in with your Todo Tree credentials to get your personalized connection URL and configuration block.

2. Deployed SSE Mode (No Local Repository Needed)

If the server has already been deployed to a cloud platform (such as Fly.io, Render, or a VPS), you do not need to clone the repository or run any code locally to connect your AI client.

Setup for Clients

1. Open the public URL of the deployed server in your browser (for example, https://your-todo-tree-mcp.com).
2. Log in with your Todo Tree credentials to access the connector dashboard.
3. The dashboard will automatically generate the required configuration for your client.
4. Copy the generated Claude Desktop configuration block.
5. Open your local Claude Desktop configuration file:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
6. Paste the configuration block inside the mcpServers object:

   {
     "mcpServers": {
       "todo-tree": {
         "url": "https://your-todo-tree-mcp.com/sse?token=YOUR_SECURE_TOKEN"
       }
     }
   }
   

7. Restart your Claude Desktop client.

3. Stdio Mode (Single User)

If no PORT is defined, the server runs in standard I/O mode. It uses a static token defined in the environment variables to authenticate all requests.

Setup for Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "todo-tree": {
      "command": "node",
      "args": ["C:\\Users\\davei\\Desktop\\todo-tree\\mcp-server\\dist\\index.js"],
      "env": {
        "TODO_TREE_API_URL": "http://localhost:1337",
        "TODO_TREE_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
PORT	No	Port to run in SSE mode. If omitted, runs in stdio mode.
TODO_TREE_API_URL	No	Base URL of the Strapi backend (defaults to http://localhost:1337).
TODO_TREE_TOKEN	No	Static JWT/token (required only for Stdio mode).

Development

Run without a build step using tsx:

PORT=3001 npm run dev

Test interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector tsx src/index.ts

Tools

get_tree

Returns the full task tree as indented text. Each line shows the task ID in brackets, completion status, due date, and child progress. Use the IDs in subsequent tool calls.

[work] : Work
  [finish-report] : Finish report
  [review-pr] : Review PR - Due: Today
[buy-groceries] : Buy groceries - Due: May 30
[call-dentist] : Call dentist

add_task

Creates a new task.

Parameter	Type	Required	Description
text	string	Yes	Task name
parent_id	string	No	ID of the parent task; omit for root level
due_date	string	No	Due date in YYYY-MM-DD format

delete_task

Permanently removes a task and all its children.

Parameter	Type	Required	Description
id	string	Yes	Task ID

complete_task

Marks a task done or undone. Completion propagates to all child tasks, same as clicking the checkbox in the UI.

Parameter	Type	Required	Description
id	string	Yes	Task ID
completed	boolean	No	true (default) to complete, false to uncomplete

set_due_date

Sets or clears the due date on a task.

Parameter	Type	Required	Description
id	string	Yes	Task ID
due_date	string	Yes	Date in YYYY-MM-DD, or "" to clear

move_task

Moves a task to a new position in the tree.

Parameter	Type	Required	Description
id	string	Yes	Task to move
target_id	string	Yes	Reference task
position	before | after | inside	Yes	before/after makes it a sibling; inside makes it a child