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 is a standalone companion project, not published to any package registry. Clone it, point it at your own running Task-Tracker instance, and wire it into your MCP client's configuration.

Requirements

• Node.js 18+

• A running Task-Tracker instance you can reach over HTTP

• That instance's API_SECRET_TOKEN (see Task-Tracker's own .env configuration)

Related MCP server: VTrack MCP Server

Install

git clone https://github.com/itlostandfound/mcp-server-tasktracker.git
cd mcp-server-tasktracker
npm install
npm run build

This produces a compiled server at dist/index.js.

Configuration

The server reads its connection details from environment variables — set these in your MCP client's configuration, not in a committed file:

The server fails fast at startup with a clear message if either required variable is missing.

Using it with an MCP client

Claude Desktop

Add an entry to claude_desktop_config.json:

{
  "mcpServers": {
    "tasktracker": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-tasktracker/dist/index.js"],
      "env": {
        "TASKTRACKER_API_URL": "http://localhost:8000",
        "TASKTRACKER_API_TOKEN": "your-api-secret-token"
      }
    }
  }
}

Claude Code

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

{
  "mcpServers": {
    "tasktracker": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-tasktracker/dist/index.js"],
      "env": {
        "TASKTRACKER_API_URL": "http://localhost:8000",
        "TASKTRACKER_API_TOKEN": "your-api-secret-token"
      }
    }
  }
}

Any other MCP-compatible client should work the same way: spawn node dist/index.js with the two environment variables set.

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

Error handling

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

• Authentication failures (401): returned as a message pointing at TASKTRACKER_API_TOKEN.

• 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

npm run dev         # run directly from source with tsx
npm run build        # compile to dist/
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.