TaskView is a self-hosted project and task management platform focused on clarity, ownership, and control. TaskView is built for teams that want a transparent, self-hosted alternative to SaaS task managers.
TypeScript graphviewkanban-boardnodejsproductivityproject-managementself-hostedtasktask-managementtask-managertodoapp
feat: http mcp
Nikolai Giman8c7be7362f11
diff --git a/build-dockers.sh b/build-dockers.shindex f0bcf3d..d0f051a 100644--- a/build-dockers.sh+++ b/build-dockers.sh@@ -37,9 +37,18 @@ cd webbash build-docker-web.sh $VERSIONcd ..+# Build CE MCP+echo "========================================="+echo "Building CE MCP Server..."+echo "========================================="+cd taskview-packages/taskview-mcp+bash build-docker-mcp.sh $VERSION gimanhead/taskview-ce-mcp+cd ../..+echo "========================================="echo "Build complete!"echo "Images built:"echo " - gimanhead/taskview-ce-api-server:$VERSION"echo " - gimanhead/taskview-ce-webapp:$VERSION"+echo " - gimanhead/taskview-ce-mcp:$VERSION"echo "========================================="diff --git a/docs/1.getting-started/2.installation.md b/docs/1.getting-started/2.installation.mdindex dcb8c07..ab9c287 100644--- a/docs/1.getting-started/2.installation.md+++ b/docs/1.getting-started/2.installation.md@@ -155,6 +155,18 @@ services:TASKVIEW_API_URL: "http://localhost:1725"ports:- "8888:80"+ # Enable to let AI assistants (Claude Code, Cursor, ...) work with your instance+ # over MCP, read https://taskview.tech/docs/integrations/mcp+ # taskview-mcp:+ # image: gimanhead/taskview-ce-mcp:latest+ # restart: unless-stopped+ # environment:+ # TASKVIEW_URL: "http://taskview-api-server:1401"+ # ports:+ # - "3100:3100"+ # depends_on:+ # - taskview-api-server+ # networks: [backend]# Enable for realtime notification read https://taskview.tech/docs/configuration/environment-variables#centrifugo-configuration-file# centrifugo:# image: centrifugo/centrifugo:v6diff --git a/docs/3.integrations/2.mcp.md b/docs/3.integrations/2.mcp.mdindex f005e4b..7335f2a 100644--- a/docs/3.integrations/2.mcp.md+++ b/docs/3.integrations/2.mcp.md@@ -7,10 +7,16 @@ navigation: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:+```-AI client ──stdio──▶ taskview-mcp ──HTTPS──▶ TaskView API+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@@ -40,6 +46,52 @@ No installation is required — the server runs via `npx`. Add it to your MCP clSet `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](/docs/getting-started/installation)):++```yaml+ 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:++```bash+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):++```json+{+ "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.+::+## PermissionsThe 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.diff --git a/taskview-packages/taskview-mcp/Dockerfile b/taskview-packages/taskview-mcp/Dockerfilenew file mode 100644index 0000000..be28e28--- /dev/null+++ b/taskview-packages/taskview-mcp/Dockerfile@@ -0,0 +1,28 @@+FROM node:24-alpine AS deps++WORKDIR /usr/src/app++COPY package.json ./+# npm cannot parse pnpm's workspace: protocol in devDependencies; only the+# runtime deps matter here, so drop the dev section before installing+RUN node -e "const p = require('./package.json'); delete p.devDependencies; require('fs').writeFileSync('package.json', JSON.stringify(p, null, 2))" \+ && npm install --omit=dev++FROM node:24-alpine++WORKDIR /usr/src/app++# npm/corepack are build-time tools; their vendored deps (tar, undici, ...)+# carry CVEs, so the runtime image ships without them+RUN rm -rf /usr/local/lib/node_modules /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack /opt/yarn* /usr/local/bin/yarn /usr/local/bin/yarnpkg++COPY --from=deps /usr/src/app/node_modules ./node_modules+COPY package.json ./+COPY dist ./dist++ENV MCP_HTTP_PORT=3100+EXPOSE 3100++USER node++CMD ["node", "dist/http.js"]diff --git a/taskview-packages/taskview-mcp/README.md b/taskview-packages/taskview-mcp/README.mdindex 568a27e..94f1954 100644--- a/taskview-packages/taskview-mcp/README.md+++ b/taskview-packages/taskview-mcp/README.md@@ -71,28 +71,71 @@ Then use `"command": "taskview-mcp"` (no `args` needed).| Variable | Required | Description ||---|---|---|| `TASKVIEW_URL` | yes | TaskView API server URL (e.g. `https://api.taskview.tech`) |-| `TASKVIEW_TOKEN` | yes | API token with `tvk_` prefix |+| `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` |++## 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:++```bash+TASKVIEW_URL=https://api.taskview.tech taskview-mcp-http+# MCP endpoint: http://localhost:3100/mcp, health check: /health+```++Connect from Claude Code:++```bash+claude mcp add --transport http taskview https://mcp.example.com/mcp \+ --header "Authorization: Bearer tvk_..."+```++or in `.mcp.json` (Claude Code, Cursor, VS Code):++```json+{+ "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.## Available tools-37 tools covering the full TaskView surface.+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`+**Tasks** — `list_tasks`, `get_task`, `create_task`, `update_task`, `delete_task`, `toggle_task_assignees`, `get_task_history`, `restore_task_from_history`**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`, `toggle_role_permission`+**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 worksThe 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.diff --git a/taskview-packages/taskview-mcp/package.json b/taskview-packages/taskview-mcp/package.jsonindex f54a9ff..8efef67 100644--- a/taskview-packages/taskview-mcp/package.json+++ b/taskview-packages/taskview-mcp/package.json@@ -4,7 +4,8 @@"description": "MCP (Model Context Protocol) server for TaskView — lets AI assistants (Claude Code, Claude Desktop, etc.) manage projects and tasks via the TaskView API","type": "module","bin": {- "taskview-mcp": "./dist/index.js"+ "taskview-mcp": "./dist/index.js",+ "taskview-mcp-http": "./dist/http.js"},"main": "./dist/index.js","files": [diff --git a/taskview-packages/taskview-mcp/src/http.ts b/taskview-packages/taskview-mcp/src/http.tsnew file mode 100644index 0000000..31e1d90--- /dev/null+++ b/taskview-packages/taskview-mcp/src/http.ts@@ -0,0 +1,105 @@+#!/usr/bin/env node+import { createServer, type IncomingMessage } from 'node:http'+import axios from 'axios'+import { TvApi } from 'taskview-api'+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'+import { createMcpServer } from './server.js'+import type { HandleMcpRequestArgs } from './http.types.js'++const TASKVIEW_URL = process.env.TASKVIEW_URL+const PORT = Number(process.env.MCP_HTTP_PORT || 3100)++if (!TASKVIEW_URL) {+ console.error('Required environment variable: TASKVIEW_URL')+ console.error('Example: TASKVIEW_URL=https://api.taskview.tech MCP_HTTP_PORT=3100 taskview-mcp-http')+ process.exit(1)+}++const CORS_HEADERS = {+ 'Access-Control-Allow-Origin': '*',+ 'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',+ 'Access-Control-Allow-Headers': 'Content-Type, Authorization, Mcp-Session-Id, MCP-Protocol-Version',+ 'Access-Control-Expose-Headers': 'Mcp-Session-Id',+}++function extractBearerToken(req: IncomingMessage): string | null {+ const header = req.headers.authorization+ if (!header?.startsWith('Bearer ')) return null+ const token = header.slice('Bearer '.length).trim()+ return token.length > 0 ? token : null+}++// Stateless mode: every request gets its own server + transport pair wired to+// an axios instance carrying ONLY this caller's token, so tokens can never+// leak between users through shared state.+async function handleMcpRequest({ req, res, token }: HandleMcpRequestArgs) {+ const $axios = axios.create({+ baseURL: TASKVIEW_URL,+ timeout: 30000,+ headers: { Authorization: `Bearer ${token}` },+ })+ const api = new TvApi($axios)+ const server = createMcpServer(api)+ const transport = new StreamableHTTPServerTransport({+ sessionIdGenerator: undefined,+ enableJsonResponse: true,+ })+ res.on('close', () => {+ transport.close()+ server.close()+ })+ await server.connect(transport)+ await transport.handleRequest(req, res)+}++const httpServer = createServer(async (req, res) => {+ for (const [name, value] of Object.entries(CORS_HEADERS)) res.setHeader(name, value)++ if (req.method === 'OPTIONS') {+ res.writeHead(204).end()+ return+ }++ const path = new URL(req.url ?? '/', 'http://localhost').pathname++ if (path === '/health') {+ res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ status: 'ok' }))+ return+ }++ if (path !== '/mcp') {+ res.writeHead(404, { 'Content-Type': 'application/json' }).end(JSON.stringify({ message: 'Not found. MCP endpoint is /mcp' }))+ return+ }++ const token = extractBearerToken(req)+ if (!token) {+ res.writeHead(401, { 'Content-Type': 'application/json', 'WWW-Authenticate': 'Bearer' }).end(+ JSON.stringify({+ jsonrpc: '2.0',+ error: { code: -32000, message: 'Unauthorized: provide your TaskView API token as "Authorization: Bearer tvk_..."' },+ id: null,+ }),+ )+ return+ }++ try {+ await handleMcpRequest({ req, res, token })+ } catch (error) {+ console.error('[mcp-http] request failed:', error)+ if (!res.headersSent) {+ res.writeHead(500, { 'Content-Type': 'application/json' }).end(+ JSON.stringify({+ jsonrpc: '2.0',+ error: { code: -32603, message: 'Internal server error' },+ id: null,+ }),+ )+ }+ }+})++httpServer.listen(PORT, () => {+ console.log(`TaskView MCP HTTP server listening on :${PORT} (endpoint /mcp), proxying to ${TASKVIEW_URL}`)+})diff --git a/taskview-packages/taskview-mcp/src/http.types.ts b/taskview-packages/taskview-mcp/src/http.types.tsnew file mode 100644index 0000000..6425fbc--- /dev/null+++ b/taskview-packages/taskview-mcp/src/http.types.ts@@ -0,0 +1,7 @@+import type { IncomingMessage, ServerResponse } from 'node:http'++export type HandleMcpRequestArgs = {+ req: IncomingMessage+ res: ServerResponse+ token: string+}diff --git a/taskview-packages/taskview-mcp/tsconfig.json b/taskview-packages/taskview-mcp/tsconfig.jsonindex d530e02..2a11f96 100644--- a/taskview-packages/taskview-mcp/tsconfig.json+++ b/taskview-packages/taskview-mcp/tsconfig.json@@ -4,6 +4,7 @@"module": "ESNext","moduleResolution": "bundler","lib": ["ES2022"],+ "types": ["node"],"strict": true,"skipLibCheck": true,"declaration": true,diff --git a/taskview-packages/taskview-mcp/vite.config.ts b/taskview-packages/taskview-mcp/vite.config.tsindex 7ab0a40..6516137 100644--- a/taskview-packages/taskview-mcp/vite.config.ts+++ b/taskview-packages/taskview-mcp/vite.config.ts@@ -4,14 +4,19 @@ import { resolve } from 'path'export default defineConfig({build: {lib: {- entry: resolve(__dirname, 'src/index.ts'),+ entry: {+ index: resolve(__dirname, 'src/index.ts'),+ http: resolve(__dirname, 'src/http.ts'),+ },formats: ['es'],- fileName: () => 'index.js',+ fileName: (_format, name) => `${name}.js`,},rollupOptions: {external: ['@modelcontextprotocol/sdk/server/mcp.js','@modelcontextprotocol/sdk/server/stdio.js',+ '@modelcontextprotocol/sdk/server/streamableHttp.js',+ 'node:http',],},target: 'node22',