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"
      }
    }
  }
}

Related MCP server: barrydo

Environment Variables

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.

delete_task

Permanently removes a task and all its children.

complete_task

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

set_due_date

Sets or clears the due date on a task.

move_task

Moves a task to a new position in the tree.