TaskLogger MCP

A Model Context Protocol server that gives AI agents programmatic access to TaskLogger.io tasks — create, update, search, assign, and complete tasks directly from an agent's toolset, no browser automation.

The server talks to the TaskLogger REST API (https://api.tasklogger.io/api/v1) over stdio. Tasks are TaskLogger logs with logTypeId = 2.

Features

• Full task lifecycle — create, update, delete, mark done
• Rich filtering — by status, priority, assignee, creator, problem type, category, company, vendor, date ranges, free-text search, and pagination
• Reference lookups — statuses, priorities, problem types, categories, sub-types, users, departments, companies
• Secure auth — password is read only from a local env file, never passed as a tool parameter
• Token persistence — access/refresh tokens cached to disk and auto-refreshed across restarts

Tools

Tool	Purpose
login	Authenticate with credentials from env vars
logout	Clear saved tokens
status	Check the authenticated user
list_tasks	List/filter/search tasks
get_task	Get one task by ID
create_task	Create a task (defaults sub-type to Report Bug)
update_task	Update fields on a task
mark_task_done	Shortcut → Completed + 100%
delete_task	Delete a task
get_statuses / get_priorities / get_problem_types / get_task_categories / get_sub_types / get_users / get_departments / get_companies	Look up valid IDs

Tasks are identified by their numeric DB id in tool calls. TaskLogger also exposes a human-friendly transaction number (TN / trans_num) in responses, which is what humans usually quote — report TN to the user, pass the numeric id to the tools.

Requirements

• Node.js 18+ (uses global fetch, FormData, crypto.randomUUID)
• An account on a TaskLogger.io branch

Setup

# 1. Clone and install
git clone https://github.com/khodorrrhajjj/TaskLogger-Mcp.git
cd TaskLogger-Mcp
npm install

# 2. Build
npm run build          # outputs dist/index.js

3. Credentials

Create a local credential file (the server reads it on startup). It is created in your home directory, deliberately outside the repo, so it is never committed.

Create ~/.tasklogger-mcp/env:

TASKLOGGER_EMAIL=you@example.com
TASKLOGGER_PASSWORD=yourpassword
TASKLOGGER_BRANCH_ID=74

• TASKLOGGER_PASSWORD is required and never passed as a tool parameter.
• TASKLOGGER_BRANCH_ID selects the branch (only needed if you have multiple).

Alternatively, set the same keys as regular environment variables in your shell.

Connecting to an agent

OpenCode

Add to opencode.json (or your project/global config):

{
  "mcp": {
    "tasklogger": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/<you>/projects/TaskLogger-Mcp/dist/index.js"],
      "env": {}
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tasklogger": {
      "command": "node",
      "args": ["C:/Users/<you>/projects/TaskLogger-Mcp/dist/index.js"]
    }
  }
}

Any other MCP client

Point it at node /absolute/path/to/tasklogger-mcp/dist/index.js over the stdio transport.

Usage examples

# List tasks pending, created by users 214/215
list_tasks  status_id="8" created_by="214,215"

# Search
list_tasks  search="product setup"

# Create a Task Logger bug report
create_task  problem_description="...bug..." problem_type_id="96" category_id="22" assigned_to_id="80"

# Update a task's status (TN 152 → Pending)
get_task  id=24077          # ← confirm the numeric id
update_task  id=24077 status_id="8"

Common status IDs: Pending = 8, To be tested = 10, Completed = 1, On Hold = 16. Sub-type Report Bug = 27. Always get_statuses / get_users to confirm current IDs.

How login works

1. On startup the server reads ~/.tasklogger-mcp/env into the process environment (existing env vars win).
2. On the first authenticated call it POSTs to /users/login with email, password, rememberMe: true, and branchId. It holds the two HttpOnly cookies the API returns:
   • accessToken — short-lived (~15 min) bearer
   • refreshToken — longer-lived (~7 days)
3. Tokens are persisted to ~/.tasklogger-mcp/auth.json (chmod 0600) so a restart doesn't force a re-login.
4. Before every request, if the accessToken is expired the server tries to refresh it (POST /users/refresh, fallback GET /users/authenticate), then falls back to a fresh env-file login.
5. The dedicated login tool re-authenticates on demand; logout clears tokens from disk.

The password itself never appears in any tool parameter, MCP log, or conversation — only inside env.