taskview-community/taskview-packages/taskview-mcp/README.md

TaskView MCP Server

MCP (Model Context Protocol) server for TaskView. Lets AI assistants like Claude Code and Claude Desktop manage projects and tasks via the TaskView API.

AI client  ──stdio──▶  taskview-mcp  ──HTTPS──▶  TaskView API

Requirements

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

Quick start

No installation needed — use npx directly in your MCP client config.

Claude Code

You can set your URL to your TaskView instance in TASKVIEW_URL.
Add to .claude/settings.json (project) or ~/.claude.json (global):

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

Claude Desktop

Add to claude_desktop_config.json:

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

Global install (optional)

If you prefer a pinned install over npx:

npm install -g taskview-mcp

Then use "command": "taskview-mcp" (no args needed).

Environment variables

Variable	Required	Description
TASKVIEW_URL	yes	TaskView API server URL (e.g. https://api.taskview.tech)
TASKVIEW_TOKEN	yes (stdio mode)	API token with tvk_ prefix. Not used in HTTP mode — each caller sends their own token
MCP_HTTP_PORT	no (HTTP mode)	Port for the HTTP server, default 3100
MCP_PUBLIC_URL	no (HTTP mode)	Public URL of this server as clients reach it — the OAuth resource identifier. Include the path when the server is mounted under one (https://api.example.com/mcp); derived from the request host when unset
MCP_ALLOWED_ORIGINS	no (HTTP mode)	Comma-separated browser origins allowed to call /mcp. Unset means no browser origin is allowed; non-browser clients send no Origin and are unaffected

HTTP server (remote / self-hosted)

Besides the local stdio mode above, the package ships an HTTP entrypoint (Streamable HTTP transport) so one shared server can serve many users — each request authenticates with the caller's own API token:

TASKVIEW_URL=https://api.taskview.tech taskview-mcp-http
# MCP endpoint: http://localhost:3100/mcp, health check: /health

Connect from Claude Code:

claude mcp add --transport http taskview https://mcp.example.com/mcp \
  --header "Authorization: Bearer tvk_..."

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

{
  "mcpServers": {
    "taskview": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer tvk_..." }
    }
  }
}

The server is stateless: every request gets its own isolated API client carrying only that caller's token. Requests without a Bearer token get 401. Self-hosted instances run their own copy next to their API (see Dockerfile in this package) — point TASKVIEW_URL at your API server and put the MCP port behind your reverse proxy with HTTPS.

OAuth (ChatGPT and other cloud clients)

Clients that will not accept a pasted API token — ChatGPT connectors among them — authorize over OAuth 2.1 instead. Nothing extra runs here: this server advertises itself as the protected resource and points at your TaskView API, which is the authorization server.

• GET /.well-known/oauth-protected-resource returns the resource metadata (RFC 9728), naming TASKVIEW_URL as the authorization server.
• A request with no token answers 401 with WWW-Authenticate: Bearer resource_metadata="…", which is what starts discovery in the client.
• The client then registers, sends the user to the TaskView consent screen, and comes back with a tvo_ access token that it sends here like any other bearer token.

Set MCP_PUBLIC_URL to the externally reachable URL of this server so the advertised resource identifier matches what clients actually request.

Mounted under a path. When the server sits behind a reverse proxy at https://api.example.com/mcp rather than on its own host, put the full path in MCP_PUBLIC_URL. RFC 9728 then places the metadata at /.well-known/oauth-protected-resource/mcp, which is where a client that computes the address from the spec — instead of trusting the WWW-Authenticate header — will look. The server publishes it at both that address and the root one, but the proxy has to route the path-inserted address here too:

location = /.well-known/oauth-protected-resource/mcp {
    proxy_pass http://127.0.0.1:3100/.well-known/oauth-protected-resource/mcp;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Manually issued tvk_ tokens keep working exactly as before — OAuth is an additional way in, not a replacement. Use tvk_ for stdio, CLIs and CI, where there is no browser to complete an authorization flow.

Available tools

61 tools covering the full TaskView surface.

Projects (Goals) — list_goals, create_goal, update_goal, delete_goal

Lists — list_lists, create_list, update_list, delete_list

Tasks — list_tasks, get_task, create_task, update_task, delete_task, toggle_task_assignees, get_task_history, restore_task_from_history

Agenda — get_agenda (today, upcoming and recently completed across all projects in one call)

Tags — list_tags, create_tag, update_tag, delete_tag, toggle_task_tag

Kanban — list_kanban_columns, create_kanban_column, update_kanban_column, delete_kanban_column

Collaboration — list_collaborators, list_collaborators_for_goal, invite_collaborator, remove_collaborator, toggle_collaborator_roles, list_roles, create_role, delete_role, list_permissions, list_role_permissions_for_goal, toggle_role_permission

Task dependencies (graph) — list_task_dependencies, add_task_dependency, delete_task_dependency

Notifications — list_notifications, mark_notification_read, mark_all_notifications_read

Organizations — list_organizations, get_organization, create_organization, update_organization, delete_organization, list_organization_members, add_organization_member, update_organization_member_role, remove_organization_member

Time tracking — start_timer, stop_timer, get_active_timer, log_time, list_time_entries, update_time_entry, delete_time_entry, get_time_summary, get_time_report, get_time_contributors

How it works

The MCP server uses the taskview-api client under the hood. Every tool call goes through the full API stack — authentication, permission checks, and validation. The MCP process itself is stateless; your token never leaves your machine except in Authorization: Bearer ... headers to your TaskView API server.

Development (from monorepo)

If you're working on the package from the TaskView monorepo:

# from repo root
pnpm build:packages
cd community/taskview-packages/taskview-mcp
pnpm build

# run directly for debugging
TASKVIEW_URL=http://localhost:3000 TASKVIEW_TOKEN=tvk_... node dist/index.js

License

See LICENSE.md in the TaskView repository.

Links

• TaskView — project repository
• Model Context Protocol — protocol specification
• Issues — bug reports & feature requests