Tududi Server

A whitelabel Model Context Protocol (MCP) server that connects LLM-powered clients to Tududi — an open-source productivity and GTD (Getting Things Done) application created by Chris Vel.

Tududi helps users organise tasks, projects, notes, and areas following GTD methodology. This MCP server acts as a bridge, allowing AI assistants (Claude, Cursor, VS Code Copilot, etc.) to read and manipulate Tududi data through a standardised protocol.

Prerequisite: You need a running Tududi instance (self-hosted) with API access enabled. The MCP server connects to Tududi's REST API and does not include the Tududi application itself.

How it works

The server exposes a single MCP endpoint at app/mcp/route.ts built on Next.js Route Handlers. On each request, it:

1. Authenticates — validates the bearer token against the Tududi instance's /api/profile endpoint.
2. Registers modules — lazily loads all 8 domain modules (tasks, projects, notes, areas, inbox, tags, profile, metrics) and registers their tools and resources with the MCP server.
3. Serves tools & resources — the connected MCP client discovers and invokes them as needed.

Authentication is handled via mcp-handler's withMcpAuth wrapper with token verification against the Tududi API.

Features

Tasks

• Tools (7): list_tasks, get_task, create_task, update_task, delete_task, toggle_task_completion, list_subtasks
• Resources (2): tududi://tasks, tududi://tasks/{uid}

Projects

• Tools (4): list_projects, create_project, update_project, delete_project
• Resources (2): tududi://projects, tududi://projects/{uid}

Notes

• Tools (4): list_notes, create_note, update_note, delete_note
• Resources (1): tududi://notes

Areas

• Tools (4): list_areas, create_area, update_area, delete_area
• Resources (1): tududi://areas

Inbox

• Tools (2): list_inbox, create_inbox_item
• Resources (1): tududi://inbox

Tags

• Tools (2): list_tags, create_tag
• Resources (1): tududi://tags

Profile

• Tools (2): get_profile, update_profile
• Resources (1): tududi://profile

Metrics

• Tools (0)
• Resources (1): tududi://metrics

Total: 25 tools and 10 resources

Prerequisites

• A running Tududi instance — self-host the original Tududi project and obtain an API token.
• Node.js 18+ or Bun runtime.

Whitelabel configuration

The server authenticates per-request using HTTP headers sent by the MCP client. The tududi-api-url header identifies the Tududi instance and the Authorization header carries the bearer token.

Client-side headers

Header	Required	Description
tududi-api-url	Yes	Base URL of the Tududi instance (e.g. https://my-tududi.com)
Authorization	Yes	Bearer token for the Tududi API (Bearer <token>)
tududi-enabled-modules	No	Comma-separated list of modules to enable; defaults to all

MCP client configuration example

{
  "mcp": {
    "servers": {
      "tududi": {
        "type": "http",
        "url": "https://my-tududi-mcp.vercel.app/mcp",
        "headers": {
          "tududi-api-url": "https://my-tududi.com",
          "Authorization": "Bearer my-api-token",
          "tududi-enabled-modules": "tasks,projects,notes"
        }
      }
    }
  }
}

Available modules

tasks · projects · notes · areas · inbox · tags · profile · metrics

Setup & running

# Install dependencies
bun install

# Development
bun dev

# Build
bun build

# Production
bun start

After starting the server, the MCP endpoint is available at http://localhost:3000/mcp.

Tech stack

• Next.js 16 (Route Handlers)
• TypeScript (strict mode)
• MCP SDK (@modelcontextprotocol/sdk)
• mcp-handler (Next.js MCP adapter with auth support)
• Zod 4 (schema validation)

Project structure

├── app/mcp/route.ts          # MCP endpoint — auth + handler setup
├── lib/tududi/
│   ├── client.ts             # HTTP client for the Tududi REST API
│   ├── config.ts             # Module names and config types
│   ├── types.ts              # Shared TypeScript types
│   └── modules/
│       ├── index.ts          # Module registry (lazy-loaded)
│       ├── tasks/            # 7 tools, 2 resources
│       ├── projects/         # 4 tools, 2 resources
│       ├── notes/            # 4 tools, 1 resource
│       ├── areas/            # 4 tools, 1 resource
│       ├── inbox/            # 2 tools, 1 resource
│       ├── tags/             # 2 tools, 1 resource
│       ├── profile/          # 2 tools, 1 resource
│       └── metrics/          # 1 resource
└── scripts/                  # Test clients

Using with MCP clients

1. Deploy this server (e.g. Vercel) or run it locally.
2. Point your MCP client to the endpoint https://your-host/mcp.
3. Set the tududi-api-url and Authorization headers as shown above.
4. The client will auto-discover all registered tools and resources.

License

MIT