taskview-community/docs/3.integrations/2.mcp.md

title, description, navigation

title	description	navigation
MCP Server	Connect AI assistants like Claude Code and Claude Desktop to TaskView via the Model Context Protocol (MCP). Manage projects and tasks with a scoped API token.	icon i-lucide-bot

TaskView ships an MCP (Model Context Protocol) server that lets AI assistants such as Claude Code and Claude Desktop work with your projects and tasks through the TaskView API.

It runs in two modes:

Local (stdio):   AI client  ──stdio──▶  taskview-mcp (npx)      ──HTTPS──▶  TaskView API
Shared (HTTP):   AI client  ──HTTPS──▶  taskview-mcp container  ──HTTP───▶  TaskView API

• Local (stdio) — each user runs the server on their machine via npx; the token lives in the client config.
• Shared (HTTP) — one server container runs next to your TaskView instance; every user connects to its URL and authenticates with their own API token per request.

Prerequisites

• Node.js >= 24
• A TaskView API token (tvk_...) — create one in your account settings. See API tokens.

Configuration

No installation is required — the server runs via npx. Add it to your MCP client config:

{
  "mcpServers": {
    "taskview": {
      "command": "npx",
      "args": ["-y", "taskview-mcp"],
      "env": {
        "TASKVIEW_URL": "https://api.taskview.tech",
        "TASKVIEW_TOKEN": "tvk_your_token_here"
      }
    }
  }
}

• Claude Code — add to .claude/settings.json (project) or ~/.claude.json (global).
• Claude Desktop — add to claude_desktop_config.json.

Set TASKVIEW_URL to your own instance when self-hosting.

Shared HTTP server (self-hosted)

The gimanhead/taskview-ce-mcp image serves MCP over HTTP (Streamable HTTP transport), so users don't need Node.js or npx — they just point their client at a URL. Add it to your docker-compose.yml next to the API (see the commented block in the installation guide):

  taskview-mcp:
    image: gimanhead/taskview-ce-mcp:latest
    restart: unless-stopped
    environment:
      # Where this MCP server forwards requests; the docker-network address
      # of your API service works best
      TASKVIEW_URL: "http://taskview-api-server:1401"
    ports:
      - "3100:3100"
    networks: [backend]

The MCP endpoint is /mcp (port 3100, configurable via MCP_HTTP_PORT), health check at /health. Every request must carry the caller's own token in the Authorization header — requests without it get 401. The server is stateless and keeps no data: each request is forwarded with exactly the token it came with.

Connect from Claude Code:

claude mcp add --transport http taskview https://mcp.your-domain.com/mcp \
  --header "Authorization: Bearer tvk_your_token_here"

or in .mcp.json (Claude Code, Cursor, VS Code):

{
  "mcpServers": {
    "taskview": {
      "type": "http",
      "url": "https://mcp.your-domain.com/mcp",
      "headers": { "Authorization": "Bearer tvk_your_token_here" }
    }
  }
}

Put the port behind your reverse proxy with HTTPS for anything beyond local use.

::callout{icon="i-lucide-info" color="neutral"} The claude.ai and Claude Desktop custom connectors UI supports only OAuth-based servers and has no field for a token header — it cannot connect to this endpoint yet. Claude Desktop users should use the local stdio configuration above instead. ::

Permissions

The assistant can only do what the API token allows. Token permissions are scoped to selected projects and intersected with your RBAC role, so an AI client never exceeds your own access. Grant the minimum scope needed.