MCP Server — Task Tracker

MCP Integration Layer  ·  Conversational Task Management  ·  TypeScript

An MCP (Model Context Protocol) server that exposes the full Task-Tracker REST API as MCP tools, enabling any MCP-compatible AI agent to manage trackers, tasks, notes, checklists, and projects conversationally. Same capabilities as the web dashboard, driven by natural language.

What It Does

  • Full API Coverage — Every Task-Tracker REST endpoint is exposed as an MCP tool, 1:1. No invented aggregates, no client-side validation duplicating what the API already does.
  • Trackers & Tasks — Create, list, update, and delete trackers and tasks. Set severity, toggle completion, reorder by drag-ID lists.
  • Rich Text Notes — Create, read, update, and delete TipTap rich-text notes attached to any task.
  • Dynamic Checklists — Full checklist CRUD, template cloning across devices, undo-delete, text and command step types with completion timestamps.
  • Projects with Steps & References — Multi-step project plans with rich-text content per step, reference links, drag-reorder, and completion toggling.
  • Fail-Fast Startup — Missing environment variables produce clear error messages at launch, not silent misconfiguration.
  • Standalone Companion — Not published to any package registry. Clone, configure, and wire into your MCP client. No global installs, no npm publish step.

Architecture

Language & Build

  • TypeScript 97.1% / JavaScript 2.9%
  • Node.js 18+ runtime
  • Compiled output at dist/index.js
  • npm run build — single compile step

MCP Protocol

  • Model Context Protocol SDK
  • Stdio transport (spawned by MCP client)
  • Tool-based API surface (no resources, no prompts)
  • Environment variable configuration

Configuration

  • TASKTRACKER_API_URL — Base URL of Task-Tracker instance
  • TASKTRACKER_API_TOKEN — API secret token
  • DEBUG — Optional request/response logging to stderr
  • Env vars set in MCP client config, not committed files

Why I Built It

Task-Tracker already had a full REST API with bearer token auth, designed from v3 to be MCP-ready. But an API is only useful if something can talk to it. The MCP server closes that gap — any MCP-compatible agent (Claude Desktop, Claude Code, Hermes, or others) can now manage my Task-Tracker instance conversationally, with the same capabilities as the web dashboard.

The 1:1 tool-to-endpoint mapping was deliberate. No aggregate endpoints that hide complexity, no client-side validation that drifts from the API. The MCP layer is a thin, honest bridge. If the API gains a new endpoint, the server gains a new tool. Simple mapping, simple maintenance.

TypeScript was the natural choice — the MCP SDK ships first-class TypeScript types, and the compiled output runs in any Node.js environment without a runtime dependency chain. Clone, build, configure, connect. That's the whole workflow.

MCP Tools

Category Tools
Trackers list_trackers, create_tracker, get_tracker, update_tracker, delete_tracker
Tasks list_tasks, create_task, get_task, update_task, delete_task
Notes list_notes, create_note, get_note, update_note, delete_note
Checklists list_checklists, create_checklist, get_checklist, update_checklist, delete_checklist, clone_checklist, undo_checklist_delete
Projects list_projects, create_project, get_project, update_project, delete_project, list_project_steps, add_project_step, reorder_project_steps, update_project_step, toggle_project_step_complete, delete_project_step
References list_step_references, add_step_reference, update_step_reference, delete_step_reference

Client Setup

Client Config Location
Claude Desktop claude_desktop_config.json — spawn node dist/index.js with env vars
Claude Code .mcp.json or claude mcp add — same JSON structure
Hermes Agent config.yaml native MCP client — stdio transport
Any MCP Client Spawn node dist/index.js with TASKTRACKER_API_URL and TASKTRACKER_API_TOKEN

Details

Status v1.0.0 · In Production
Language TypeScript 97.1% · JavaScript 2.9%
Runtime Node.js 18+
License MIT
Source GitHub — itlostandfound/mcp-server-tasktracker
Requires Task-Tracker v3.0.x instance with API access