TaskMCP

A personal task management system with a lightweight Web UI and a Model Context Protocol (MCP) server.

Features

• Local-first SQLite storage.
• MCP server for LLM clients (stdio transport).
• Terminal-inspired Web UI with React + Tailwind CSS v4.
• Drag-and-drop task cards across status columns.
• Inline card editing and per-column task creation.
• Projects, tasks, labels, and comments.
• Both LLM and browser write to the same database.

Architecture

TaskMCP runs as two independent processes that share a single SQLite file:

• npm run mcp — MCP server on stdio for LLM clients.
• npm run web — Hono web server on http://localhost:3000.

Both processes open the same better-sqlite3 database configured with WAL mode and a 5 second busy timeout, so they can run concurrently without blocking each other.

Installation

npm install

Scripts

• npm run build — Compile TypeScript.
• npm run typecheck — Run TypeScript without emitting files.
• npm run test — Run Vitest tests.
• npm run mcp — Start the MCP server (stdio).
• npm run web:build — Build the React client and Tailwind CSS output.
• npm run web:watch — Run the web server with automatic client rebuilds on file changes.
• npm run web:serve — Start only the Hono API/static server.
• npm run web — Build and start the web UI on http://localhost:3000.
• npm run css:build — Build the Tailwind CSS output.
• npm run design:lint — Validate DESIGN.md.
• npm run design:export — Export design tokens to src/web/static/theme.css.
• npm run lint — Run ESLint.
• npm run format — Format files with Prettier.

Design System

Visual tokens are defined in DESIGN.md. Export them and rebuild CSS with:

npm run design:export
npm run css:build

The front-end is built with React, bundled by esbuild, and styled with Tailwind CSS v4 classes generated from src/web/client/index.css.

Note: The @google/design.md v0.3.0 export CLI does not emit CSS correctly, so design:export runs a small local script (scripts/generate-theme.js) that parses DESIGN.md and generates the equivalent Tailwind v4 @theme block.

Configuration

Set TASKMCP_DB_PATH to override the default SQLite database location (.data/taskmcp.db).

API Endpoints

All endpoints are mounted under /api:

Method	Endpoint	Description
GET	/api/projects	List all projects
GET	/api/labels	List all labels
GET	/api/tasks	List tasks (query: projectId, status, label, query)
GET	/api/tasks/:id	Get a single task
POST	/api/tasks	Create a task
PATCH	/api/tasks/:id	Update a task
DELETE	/api/tasks/:id	Delete a task
POST	/api/tasks/:id/comments	Add a comment

Usage Workflows

Add a task through your LLM client

1. Configure the MCP client (see below).
2. Ask it to create a task:

   在收件箱项目里创建一个标题为 "Review design system" 的高优先级任务。
   

3. The task is written to .data/taskmcp.db.

View and edit tasks in the browser

1. Start the web server:

   npm run web
   

2. Open http://localhost:3000.
3. Use the search box, status filter, or label filter to find tasks.
4. Click a task card to edit, change status, add comments, or delete it.

Both interfaces share the same data

Because MCP and Web open the same SQLite file, any change from one side appears in the other immediately after a refresh.

MCP Clients

Replace /path/to/CcTaskMCP with the actual project path.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "taskmcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/CcTaskMCP/src/mcp/index.ts"]
    }
  }
}

opencode (opencode.json)

{
  "mcp": {
    "taskmcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/CcTaskMCP/src/mcp/index.ts"]
    }
  }
}

Note on the MCP SDK

The plan originally referenced @modelcontextprotocol/sdk@^2.x; npm currently ships 1.29.0 as the latest stable release. The server is implemented with the v1 McpServer API and is functionally equivalent for this project.

License

MIT