mcp-server-tasktracker

An MCP (Model Context Protocol) server for AI integration into Task-Tracker.

It exposes the full Task-Tracker REST API — trackers, tasks, notes, checklists, and projects (with steps and references) — as MCP tools, so any MCP-compatible AI agent (Claude Desktop, Claude Code, or others) can manage your Task-Tracker instance conversationally, with the same capabilities as the web dashboard.

This server is designed to run remotely — one long-running instance (typically in Docker) that any number of MCP clients connect to over HTTP, each authenticating with their own Task-Tracker token. It does not run as a local subprocess of your MCP client.

Requirements

• Docker (recommended) or Node.js 18+, to run the server itself somewhere reachable over HTTP

• A running Task-Tracker instance the server can reach over HTTP

• A Task-Tracker API_SECRET_TOKEN for each person/client that will connect (see Task-Tracker's own .env configuration) — this token is supplied by each client, not configured on the server (see Configuration)

Related MCP server: mcp-task-manager

Install

Docker (recommended)

Pull the latest image from DockerHub and run it as a long-lived service:

docker pull itlostandfound/mcp-server-tasktracker:latest
docker run -d --name mcp-server-tasktracker \
  -p 3000:3000 \
  -e TASKTRACKER_API_URL=http://your-tasktracker-host:8000 \
  itlostandfound/mcp-server-tasktracker:latest

Note: if Task-Tracker runs on the same host as this container, localhost inside the container refers to the container itself, not the host. Use http://host.docker.internal:8000 (Docker Desktop) or --add-host=host.docker.internal:host-gateway (Linux) instead.

Docker Compose

Copy env.example.txt to .env and fill in TASKTRACKER_API_URL, then:

docker compose up -d

This exposes the server on 3000:3000 directly. If you're putting it behind a domain with TLS via Traefik, use compose.traefik.yml instead (also set MCP_DOMAIN in .env to the bare hostname, and pre-create the external network with docker network create traefik):

docker compose -f compose.traefik.yml up -d

Once it's up, your MCP client connects to https://<MCP_DOMAIN>/mcp — don't forget the /mcp path, and don't put a scheme in MCP_DOMAIN itself (see Configuration).

From source

git clone https://github.com/itlostandfound/mcp-server-tasktracker.git
cd mcp-server-tasktracker
npm install
npm run build
TASKTRACKER_API_URL=http://localhost:8000 npm start

Configuration

The server itself only needs to know where Task-Tracker lives — it holds no Task-Tracker credential of its own:

The server fails fast at startup with a clear message if TASKTRACKER_API_URL is missing.

The URL your MCP client actually connects to is https://<MCP_DOMAIN>/mcp — the /mcp path is required. MCP_DOMAIN itself must stay a bare hostname (no scheme, no path) because it's used both to build the Traefik router rule and, verbatim, as the value checked against the request's Host header — a scheme or path there will break routing/host validation, not the client URL. The client-facing URL where you add /mcp is a separate, unrelated string; see Using it with an MCP client below.

The Task-Tracker API_SECRET_TOKEN is supplied per-connection by each MCP client, as a standard Authorization: Bearer <token> header on every request to /mcp — never as a server-side environment variable. The server uses whatever token arrives with a given request to talk to Task-Tracker on that caller's behalf, so different clients can be granted different Task-Tracker tokens/permissions without any server-side configuration change. A request with a missing or malformed Authorization header is rejected with 401 before any Task-Tracker call is made.

Using it with an MCP client

The server exposes a single endpoint, POST /mcp (Streamable HTTP, stateless — no server-side sessions), at whatever host/port you deployed it to. Each client config points at that URL and supplies its own token via a header.

Claude Code

Add to your project or user MCP configuration (.mcp.json or via claude mcp add):

{
  "mcpServers": {
    "tasktracker": {
      "type": "http",
      "url": "https://your-server-host:3000/mcp",
      "headers": {
        "Authorization": "Bearer $TASKTRACKER_API_TOKEN"
      }
    }
  }
}

$TASKTRACKER_API_TOKEN is expanded from your own local environment when Claude Code starts — the token lives on your machine, not the server. Set it locally with export TASKTRACKER_API_TOKEN=your-api-secret-token (or hardcode the value directly in the headers block if you prefer).

Known client bug: some Claude Code versions have shipped with bugs where configured headers aren't attached to Streamable HTTP requests (see #48514, #50464, #59467). If the server always responds 401, confirm your Claude Code version actually sends the header before assuming this project is misconfigured.

Claude Desktop

Claude Desktop's remote MCP support varies by version — consult Anthropic's current docs for how your version accepts a custom Authorization header for a url-type server entry, then use the same url/token pairing as above.

Other MCP clients

Any client that supports the Streamable HTTP transport with custom headers works the same way: point it at https://your-server-host:3000/mcp and set Authorization: Bearer <your-tasktracker-token>.

Tools

Every tool mirrors a Task-Tracker API endpoint 1:1 — no invented aggregate operations, no client-side validation duplicating what the API already does.

Trackers

Tasks

Notes

Checklists

Projects, Steps & References

Rich-text content (notes & project steps)

create_note, update_note, add_project_step, and update_project_step all take a content field. Task-Tracker stores this internally as a TipTap JSON document, but you don't need to construct that by hand — pass a plain string of Markdown or plain text and it's converted automatically:

{ "content": "Goal: create the widget\n\n## Sub-tasks\n\n1. Create directory\n2. Init package.json" }

Supported Markdown: paragraphs, # headings, **bold**, _italic_, `inline code`, [links](url), bullet (-) and numbered (1.) lists, > blockquotes, fenced code blocks, and hard line breaks. Constructs the converter doesn't understand (tables, images, raw HTML, task-list checkboxes) are never silently dropped — they degrade to plain text so the content survives, just not as their intended rich element.

If you need something the converter can't express exactly, you can still pass a raw TipTap JSON document directly instead of a string — it's stored as-is.

For project steps, content_text (used for search) is derived automatically from content when omitted, so you only need to write the text once. Pass content_text explicitly if you want the search index to see different text than what's rendered.

Error handling

• Missing/malformed Authorization header: rejected with HTTP 401 before any tool runs or any Task-Tracker call is made.

• Connection failures (Task-Tracker unreachable): returned as a clear message naming the configured URL, not a stack trace.

• Authentication failures (Task-Tracker rejects the supplied token): returned as a clear message, without echoing the token back.

• Validation errors: the API's own FastAPI/Pydantic error details are passed through as-is.

• Unexpected/non-JSON responses (e.g. a reverse proxy error page instead of the API): surfaced as a clear message rather than crashing on an invalid-JSON parse.

• Destructive operations (deletes): exposed as plain tools with no extra confirmation step — the same trust model as calling the API directly. Only checklists support undo_checklist_delete; other deletes are permanent.

Development

TASKTRACKER_API_URL=http://localhost:8000 npm run dev   # run the HTTP server directly from source with tsx
npm run build        # compile to dist/
TASKTRACKER_API_URL=http://localhost:8000 npm start      # run the compiled server (dist/index.js)
npm run typecheck    # type-check without emitting
npm test             # run the automated test suite (mocked HTTP, no live Task-Tracker needed)

Compatibility

Built and tested against Task-Tracker v3.0.x's /api/v1 REST API. Versioned independently of Task-Tracker itself, starting at v1.0.0.

License

MIT — see LICENSE.