@ainovix/taskmanager-mcp

MCP server for TaskManager — exposes task management as AI-consumable tools over the Model Context Protocol.

What is this?

This package lets AI assistants (OpenCode, Claude Desktop, Cursor, etc.) interact with TaskManager through natural language. It connects to the TaskManager REST API and exposes 18 tools that AI models can call to list, create, update, and manage tasks.

Installation

No installation needed. Run directly via npx:

npx -y @ainovix/taskmanager-mcp

Requires Node.js 18+.

Configuration

Set the following environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TASKMANAGER_API_KEY | Yes | — | API key from TaskManager (Settings > API Keys) | | TASKMANAGER_API_URL | Yes | — | Base URL for your TaskManager instance (e.g. https://your-domain.com) |

Generate an API Key

1. Log in to TaskManager
2. Go to Settings > API Keys (admin) or Profile > API Keys (all roles)
3. Click Generate New Key, copy the key immediately (shown only once)

Available Tools

| Tool | Description | |------|-------------| | auth_validate | Validate the API key and return the current user's identity | | list_tasks | List tasks visible to the authenticated user (supports pagination and status filter) | | get_task | Get a single task by its ID | | create_task | Create a new task (requires title and area_id) | | update_task | Update task fields (title, description, assigned_to, due_date) | | update_task_status | Change task status (open, in-progress, completed, accepted, rejected) | | delete_task | Soft-delete a task (admin and manager roles only) | | add_comment | Add a comment to a task (types: comment, observation, blocker) | | list_comments | List all comments on a task | | list_activities | List activity history for a task | | get_dashboard_stats | Get task count statistics (by status, overdue, etc.) | | add_subtask | Add a subtask to a task | | update_subtask | Update a subtask's title or description | | toggle_subtask | Mark a subtask as completed or incomplete | | delete_subtask | Delete a subtask | | list_areas | List all organizational areas | | list_users | List all users (admin and manager roles only) | | list_priorities | List all priority levels |

MCP Client Configuration

OpenCode (opencode.jsonc)

{
  "mcp": {
    "taskmanager": {
      "type": "local",
      "command": ["npx", "-y", "@ainovix/taskmanager-mcp"],
      "enabled": true,
      "environment": {
        "TASKMANAGER_API_KEY": "{env:TASKMANAGER_API_KEY}",
        "TASKMANAGER_API_URL": "{env:TASKMANAGER_API_URL}"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "taskmanager": {
      "command": "npx",
      "args": ["-y", "@ainovix/taskmanager-mcp"],
      "env": {
        "TASKMANAGER_API_KEY": "tmk_live_your_key_here",
        "TASKMANAGER_API_URL": "https://your-taskmanager-instance.com"
      }
    }
  }
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Run locally (requires TASKMANAGER_API_KEY)
TASKMANAGER_API_KEY=tmk_live_... pnpm start

Project Structure

packages/mcp-server/
  src/
    index.ts       — Entry point (stdio transport)
    server.ts      — MCP server with 18 tool registrations
    client.ts      — HTTP client for TaskManager REST API
    config.ts      — Environment variable loading and validation
    errors.ts      — Error types (McpHttpError, ConfigError)
  tests/
    config.test.ts — Config validation tests
    client.test.ts — HTTP client tests (mocked fetch)
    server.test.ts — Tool registration tests

Publishing

pnpm build
npm publish --access public

Why TypeScript instead of Python?

The original MCP design specified a Python implementation. We deliberately chose TypeScript (Node.js) for these reasons:

• Ecosystem parity: The TaskManager frontend is a Next.js app — the team's primary stack is TypeScript. A Node.js MCP server means zero context-switching and shared tooling.
• Zero-install via npx: Publishing to npm lets users run npx -y @ainovix/taskmanager-mcp without installing Python, managing virtualenvs, or dealing with pip dependencies.
• Shared team skills: Every team member can read, review, and contribute to the MCP server without learning Python.
• Same protocol, same behavior: The MCP protocol is transport-agnostic. The TypeScript implementation exposes identical tools and follows the same schema — the client experience is unchanged.

License

MIT