@aegisx/taskflow-mcp

MCP (Model Context Protocol) server that lets Claude — in Claude Desktop, Claude Code, or any MCP client — operate the full TaskFlow surface mid-conversation: work items, meetings, incidents, vendors, sprints, KB articles, RFCs, approvals, time tracking, and more.

v1.0 — 254 tools across 32 domain groups. See the matrix below for what's covered.

Tool coverage

| Domain | Module file | Tools | What it covers | |---|---|---:|---| | Work items | workitems.ts | 21 | create / get / list / update / status transition / delete-restore-purge / subtasks / history / comments / bulk update / links / reactions / pending / parse-import-export | | Meetings | meetings.ts | 17 | meeting CRUD + attendees + links (incl. Miro) + attachments — full minutes flow | | Incidents | incidents.ts | 6 | open / list / get / update / append-timeline / single transition tool (acknowledge → identify → monitor → resolve → postmortem → close → reopen) | | Vendors | vendors.ts | 9 | vendor CRUD + visit CRUD (post-visit minutes / follow-ups) | | RFCs | rfcs.ts | 5 | list / get / create / update / decide (submit→approve→reject→start→complete) | | Sprints | sprints.ts | 10 | sprint CRUD + transitions + items + metrics + hill-chart | | Retros | retros.ts | 6 | get / create / update / vote / auto-import / publish-to-KB | | KB | kb.ts | 21 | category CRUD + article CRUD + trash/restore + feedback + stats + work-item links / entity refs / related-articles | | Service Desks | service-desks.ts | 10 | desk CRUD + member CRUD + my-desks | | Approvals | approvals.ts | 4 | list / create-chain / decide / cancel | | Directives | directives.ts | 8 | directives + sources + overdue list | | Notifications | notifications.ts | 6 | inbox + unread + mark-read + prefs (in-app/email/LINE) | | DM | dm.ts | 8 | threads + messages + read state + edit/delete | | Time logs | time-logs.ts | 5 | manual entries + summary aggregations | | Posts | posts.ts | 12 | list / CRUD / pin / reactions / comments / publish-to-KB | | Bookmarks | bookmarks.ts | 4 | list / create / check / count | | Task templates | task-templates.ts | 6 | template CRUD + apply (spawn work items) | | Trainings | trainings.ts | 9 | training CRUD + attendee CRUD + attendance | | Recurring | recurring.ts | 4 | scheduled spawn rules (cron + cadence) | | Check-ins | check-ins.ts | 5 | series CRUD + runs | | Catalog (cats/teams/members) | catalog.ts | 16 | full CRUD on categories, teams, members + my-profile + workload | | Custom fields | custom-fields.ts | 6 | definitions + per-work-item values | | Modules / Features | modules.ts | 9 | module CRUD + feature CRUD | | Webhooks | webhooks.ts | 5 | subscription CRUD + delivery log | | Reports | reports.ts | 8 | dashboard / monthly / compensation / cycle-time / leaderboard / activity-graph / achievements | | Assets | assets.ts | 5 | asset CRUD | | Quotations | quotations.ts | 4 | list / get / create / delete | | Rate cards | rate-cards.ts | 10 | card CRUD + version + history + tiers + adjustments + calculate + estimate | | Board (kanban) | board.ts | 9 | config + cards + custom views | | Releases | releases.ts | 3 | log_release_activity / list_recent_releases / get_release_log | | Timer | timer.ts | 2 | start / stop | | Search | search.ts | 1 | universal search |

Intentionally NOT exposed

| Endpoint | Why it's excluded | |---|---| | */tick (sla, recurring, check-ins) | cron-internal — not for client use | | /socket.io/, /api/board/events | realtime streams (websocket / SSE) — wrong shape for MCP | | upload POST | binary multipart — handled by web uploader | | releases.create, releases/:v/activities (lifecycle) | release flow is CI/release.sh only | | admin/backup-status, admin/mail-test | ops-UI internals | | line/* | OAuth callback chain | | api-keys mutations | auth flow — admin web only | | users admin mutations | sensitive — admin web only | | webhooks/test | debug endpoint |

Release log tools — extra setup

log_release_activity, list_recent_releases, and get_release_log hit admin-only endpoints. The configured TASKFLOW_API_KEY must include admin in its permissions (set when creating the key at /admin/api-keys). A regular read/write key will get 403 from these three tools. Admin-only endpoints in other groups (Reports, Webhooks, Modules, Features, Assets, Members CRUD) need the same admin permission.

log_release_activity is intentionally restricted to observational events: note, mcp.action, investigate.started, investigate.completed, fix.applied, incident.linked. Lifecycle events (build.succeeded/deploy.succeeded/rollback) are NOT exposed because those must come from CI or scripts/deploy.sh to keep the audit trail trustworthy. If you (Claude) deployed something manually via shell, log a note describing what happened — don't post deploy.succeeded directly.

Every activity posted via MCP is tagged actorType: "mcp" and shows in the admin UI with the purple ✨ marker.

Install — pick one

A. npm / npx (recommended for end users)

Once published to npm, no install step needed — npx runs it on demand. Just put this in your MCP client config:

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "..." }
    }
  }
}

For permanent install:

npm install -g @aegisx/taskflow-mcp

B. Single-file download from GitHub Releases (Node 18+ only — no npm)

mkdir -p ~/.local/bin
curl -L -o ~/.local/bin/taskflow-mcp \
  https://github.com/aegisx-platform/taskflow/releases/latest/download/bundle.js
chmod +x ~/.local/bin/taskflow-mcp

C. Build from source (developer / monorepo)

git clone https://github.com/aegisx-platform/taskflow.git
cd taskflow/packages/mcp-taskflow
bash install.sh

Installer builds the bundle, drops it in ~/.local/bin/taskflow-mcp, prints the JSON config to paste. Override location with INSTALL_DIR=/usr/local/bin bash install.sh.

D. Tarball (air-gapped)

Download aegisx-taskflow-mcp-X.Y.Z.tgz from GitHub Releases, copy to target machine, then:

npm install -g ./aegisx-taskflow-mcp-*.tgz

Publishing (maintainers only)

Cutting a new release:

git tag mcp-v0.1.0
git push origin mcp-v0.1.0

The mcp-release.yml workflow will:

1. Build the bundle
2. Pack the tarball
3. Upload bundle.js + .tgz to GitHub Releases
4. Publish to npm — only if NPM_TOKEN secret is set in repo settings

To enable npm publish:

1. Sign up at https://www.npmjs.com (or use existing account)
2. Run npm token create --type=automation → copy the token
3. Repo Settings → Secrets and variables → Actions → New repository secret → name NPM_TOKEN, paste value
4. Next tag push will publish

Configure

The minimal config needs only TASKFLOW_API_KEY — TASKFLOW_BASE_URL defaults to https://taskflow.kkh.go.th (KKH production). For self-hosted or local dev, override TASKFLOW_BASE_URL.

Where to get the values

• TASKFLOW_API_KEY → Admin → API Keys in TaskFlow, create a key with write permission. Token is shown once, copy immediately.
• TASKFLOW_BASE_URL → optional — defaults to https://taskflow.kkh.go.th. Set only for self-hosted (https://your-taskflow.example.com) or local dev (http://localhost:3001).
• TASKFLOW_MEMBER_ID → optional. See "Two auth modes" below.

Restart the client after editing the config.

Client config examples

Pick your AI client below. All examples assume the npx-on-demand install (no global install required).

Claude Code (CLI)

CLI one-liner:

claude mcp add taskflow -- npx -y @aegisx/taskflow-mcp@latest
# then set the env var in the same scope
claude mcp add-env taskflow TASKFLOW_API_KEY tfk_xxxxxxxxxxxx

Or edit ~/.claude.json / project .mcp.json directly:

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
    }
  }
}

Claude Desktop sometimes has a slimmed-down PATH. If npx isn't found, use the absolute path: "command": "/usr/local/bin/npx" (or wherever which npx reports).

Claude.ai (web / mobile, Pro/Team/Enterprise)

Settings → Integrations → Add custom integration. Paste the npm command — Claude.ai treats @aegisx/taskflow-mcp as a remote MCP server via npx. Set TASKFLOW_API_KEY in the integration env.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
    }
  }
}

Then in Cursor: Settings → MCP → Refresh — taskflow should appear with green status.

Windsurf (Codeium)

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
    }
  }
}

Restart Windsurf, then check Cascade panel → MCP servers.

VS Code (GitHub Copilot Chat — agent mode)

Open Command Palette → MCP: Add Server → choose npm package → enter @aegisx/taskflow-mcp. Or edit .vscode/mcp.json:

{
  "servers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
    }
  }
}

Switch Copilot Chat to Agent mode to see TaskFlow tools.

Cline (VS Code extension)

In VS Code: Cline panel → MCP Servers → Edit Configuration (opens cline_mcp_settings.json):

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Continue.dev

Edit ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@aegisx/taskflow-mcp@latest"]
        },
        "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
      }
    ]
  }
}

Zed

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "taskflow": {
      "command": {
        "path": "npx",
        "args": ["-y", "@aegisx/taskflow-mcp@latest"],
        "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
      }
    }
  }
}

JetBrains AI Assistant (IntelliJ / WebStorm / PyCharm / etc.)

Settings → Tools → AI Assistant → MCP Servers → Add:

• Name: taskflow
• Command: npx
• Args: -y @aegisx/taskflow-mcp@latest
• Env: TASKFLOW_API_KEY=tfk_xxxxxxxxxxxx

Goose (Block)

goose mcp add taskflow npx -y @aegisx/taskflow-mcp@latest \
  --env TASKFLOW_API_KEY=tfk_xxxxxxxxxxxx

Or edit ~/.config/goose/profiles.yaml and add under tools.mcp.servers.

Aider

aider --mcp-server taskflow=npx -y @aegisx/taskflow-mcp@latest \
  --mcp-env taskflow=TASKFLOW_API_KEY=tfk_xxxxxxxxxxxx

Gemini CLI

Edit ~/.config/gemini-cli/config.json:

{
  "mcpServers": {
    "taskflow": {
      "command": "npx",
      "args": ["-y", "@aegisx/taskflow-mcp@latest"],
      "env": { "TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx" }
    }
  }
}

Copilot CLI

gh copilot mcp add taskflow \
  -- npx -y @aegisx/taskflow-mcp@latest
gh copilot mcp env taskflow TASKFLOW_API_KEY tfk_xxxxxxxxxxxx

ChatGPT (Developer Mode / Agents)

ChatGPT now accepts MCP servers in Developer Mode (Plus/Team/Enterprise). Settings → Connectors → Add MCP server:

• Name: TaskFlow
• Command: npx -y @aegisx/taskflow-mcp@latest
• Env: TASKFLOW_API_KEY=tfk_xxxxxxxxxxxx

For Agents Builder: import as a Tool → MCP with the same command.

OpenAI Agents SDK (programmatic)

from agents import Agent
from agents.mcp import MCPServerStdio

taskflow = MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@aegisx/taskflow-mcp@latest"],
        "env": {"TASKFLOW_API_KEY": "tfk_xxxxxxxxxxxx"},
    }
)

agent = Agent(name="taskflow-agent", mcp_servers=[taskflow])

Self-hosted / local dev override

For any client above, just add TASKFLOW_BASE_URL to the env block:

"env": {
  "TASKFLOW_API_KEY":  "tfk_xxxxxxxxxxxx",
  "TASKFLOW_BASE_URL": "http://localhost:3001"
}

Two auth modes (member resolution)

list_my_tasks and create_work_item (default assignee) need a client-side "who am I" identity. (start_timer doesn't — the API resolves the actor server-side from the key.) There are two ways to provide identity to the client:

| Mode | When | Config | |---|---|---| | User-bound API key (recommended for individuals) | The API key is tied to one specific member. Most personal-use keys are like this — when you generate the key from Admin → API Keys while logged in as yourself. | Just set TASKFLOW_API_KEY. The MCP calls GET /api/members/me once and caches the resolved member id. | | Shared / admin / act-as key | The key isn't tied to one user (e.g. an integration key, or an admin key acting on behalf of someone else). | Set both TASKFLOW_API_KEY and TASKFLOW_MEMBER_ID to the numeric member id you want to act as. Env always wins over /members/me so admins can target any member explicitly. |

Find member ids at Admin → Members (numeric id column) or via GET /api/members/me with your key.

Example prompts

"ช่วยสร้าง ticket ใน TaskFlow เรื่อง 'ติดตั้งคอม OPD ห้อง 3' ความสำคัญ high กำหนดเสร็จศุกร์นี้"

"What's on my plate today?" → list_my_tasks

"Mark TKT-2026-014 as in_progress and start the timer on it"

"Search for KB articles about VPN"

Meeting flow — paste a transcript:

"Update meeting #42 with this minutes + decisions, then create a work item for each action item I mention and link them back to the meeting."

Calls: update_meeting → create_work_item (loop) → add_meeting_link (with the work-item URLs).

Incident flow — production breaking:

"Open a high-severity incident: API throwing 500s, then keep adding to the timeline as I investigate."

Calls: create_incident → transition_incident('acknowledge') → add_incident_timeline (loop) → transition_incident('identify') with root cause → transition_incident('resolve') → create_kb_article for the postmortem.

Vendor visit — after a vendor meeting:

"Log today's vendor visit with vendor #7 — purpose was scoping the new HIS upgrade, attendees were the IT team, here are my notes:..."

Calls: create_vendor_visit then maybe create_work_item for follow-ups.

Sprint planning:

"List active sprints, then add TKT-2026-001..010 to the current dev sprint."

Calls: list_sprints({ active_only: true }) → add_sprint_items.

Auth model

X-API-Key header secures every call — it's the security boundary, guard it like a password. Client-side caller identity (used to fill assignedTo and to drive list_my_tasks) is resolved from /members/me for user-bound keys, or from the optional TASKFLOW_MEMBER_ID env var when using a shared/admin key. See "Two auth modes" above. Server-side actor resolution (used by start_timer, audit log, etc.) is always done from the API key on the server.

Development

pnpm install
pnpm build     # type-check + emit
pnpm test      # vitest registry smoke tests
pnpm bundle    # produces dist/bundle.js (single self-contained file)

Don't use pnpm dev (tsx watch) while a live MCP client is attached — tsx's reload messages go to stdout and corrupt the JSON-RPC stream. Use pnpm bundle then restart the client.

Layout

Each domain group is a separate file in src/tools/<group>.ts exporting a readonly <group>Tools: ToolModule array. src/index.ts flattens all groups into a single registry, asserts unique tool names, and dispatches incoming tools/call requests through Zod arg-validation to the matching handler. Adding a new tool = define an entry in the relevant group file — no separate registration step.