TaskHub 任务管理 MCP 服务器

TaskHub MCP Server

MCP (Model Context Protocol) server for TaskHub — full platform control via Claude Code.

Tools for managing tasks, projects, organizations, comments, notifications, invitations, and activity — all from your terminal through Claude.

Quick Start

1. Add to Claude Code config

Add to your .mcp.json (project or global):

{
  "mcpServers": {
    "taskhub": {
      "command": "node",
      "args": ["/path/to/taskhub-mcp/dist/index.js"],
      "env": {
        "TASKHUB_API_URL": "http://localhost:3001/api",
        "TASKHUB_API_TOKEN": "<project-bound-api-key>"
      }
    }
  }
}

Or install from GitHub:

{
  "mcpServers": {
    "taskhub": {
      "command": "npx",
      "args": ["github:jose890823/taskhub-mcp"],
      "env": {
        "TASKHUB_API_URL": "https://api.taskhub.com/api",
        "TASKHUB_API_TOKEN": "<project-bound-api-key>"
      }
    }
  }
}

2. Configure the API key

Create a project-bound TaskHub API key, provide it as TASKHUB_API_TOKEN in the MCP host environment, and restart the MCP process after changing it. The key is loaded once and held in memory only; it is not persisted, refreshed, converted, or recoverable by the server.

Use taskhub_whoami to validate the key and inspect server metadata. There is no password login or JWT migration path.

3. Link a project

Use taskhub_connect with slug "my-project"

This creates .taskhub.json in your working directory. Subsequent task operations auto-target this project.

Environment Variables

Remote API URLs must use HTTPS. Plain HTTP is reserved for local development with localhost or 127.0.0.1.

Tools

Auth & System

Context

Search

Organizations

Projects

Tasks

Comments

Notifications

Activity

Smart Project Detection

When you run taskhub_connect, a .taskhub.json file is created in your directory:

{
  "projectId": "uuid",
  "projectName": "My Project",
  "projectSlug": "my-project",
  "systemCode": "PRJ-260219-A3K7",
  "organizationId": "uuid",
  "organizationName": "My Org"
}

This enables:

• taskhub_task_create auto-assigns to the linked project
• taskhub_tasks_list auto-filters by the linked project
• Project-sensitive requests use one effective project ID; missing, ambiguous, or mismatched context fails closed rather than switching key bindings

Authorization and failure contract

The client performs advisory scope preflight through GET /auth/mcp-scopes and may cache the result for five minutes. The cache never authorizes a request or overrides server-side key validity, scopes, revocation, or project binding.

Only these confirmed backend combinations receive classified guidance:

Unknown status/code combinations use generic safe guidance. Tokens, passwords, authorization headers, endpoint configuration, and raw backend details are not returned in tool errors or startup diagnostics.

taskhub_whoami is metadata-only: it reports user metadata, server scopes, and local/effective context, never the API key.

Migration, rollout, and rollback

1. Create a new project-bound key; do not convert a password, JWT, or legacy key.
2. Configure TASKHUB_API_TOKEN outside source control and validate with taskhub_whoami.
3. Link the working directory with taskhub_connect and verify the effective project before project-sensitive operations.
4. For a revoked, expired, or inactive key, revoke it at the server, create a replacement, update the host environment, and restart the MCP process.

To roll back a deployment, stop the MCP process and restore the previously published version from its versioned source or package. Reconfigure the environment as required; never restore or copy credential files. Any live or mutating validation for this migration must be explicitly opted in; its harness conversion is tracked separately and is not part of this documentation slice.

Package/release validation and the remaining migration test work are tracked separately; this README does not claim those checks have passed.

Development

pnpm install
pnpm build       # Compile TypeScript
pnpm dev         # Watch mode
pnpm start       # Run compiled server

License

MIT