taskboard-mcp

A small MCP server for task/todo tracking — structured, deterministic, no AI involved in the tool itself. Built for LLM agents (or anyone) that need to track work across sessions without paying the token cost of hand-editing a growing text file on every status change.

Why

Text-file task trackers (a TASKS.md you hand-edit) work, but get expensive to maintain as they grow — every update means finding and rewriting a chunk of existing text. A proper tool takes a few structured arguments (task_update(id, state="done")) instead, and does the file/DB I/O itself.

Design

TypeScript, built on the official MCP SDK.
SQLite-backed storage (better-sqlite3) — structured, queryable, deterministic.
Tasks are scoped by project/board, so one server instance can track work across many unrelated projects — scope is a first-class filter on every tool.
Communicates over stdio, like any standard MCP server.

Tools

Tool	Arguments	Description
`task_add`	`scope`, `content`	Create a new task (starts in state `open`).
`task_update`	`id`, and any of `scope`, `content`, `state`	Update fields on an existing task.
`task_list`	optional `scope`, `state`	List tasks, filtered by scope and/or state.
`task_complete`	`id`	Shorthand for `task_update(id, state="done")`.
`task_delete`	`id`	Permanently delete a task.

Valid state values: open, in_progress, done.

Every task has: id, scope, content, state, created_at, updated_at, completed_at.

Install

git clone https://github.com/fellam/taskboard-mcp.git
cd taskboard-mcp
npm install
npm run build

This produces dist/index.js, a runnable Node entrypoint that speaks MCP over stdio.

Usage

Storage location

By default, data is stored in a SQLite file at ~/.taskboard-mcp/tasks.db. Override with the TASKBOARD_DB_PATH environment variable to point at a different file (or :memory: for an ephemeral in-process database, mainly useful for testing).

Wiring into Claude Code (`.mcp.json`)

Add this to your project's .mcp.json (or claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "taskboard": {
      "command": "node",
      "args": ["/absolute/path/to/taskboard-mcp/dist/index.js"],
      "env": {
        "TASKBOARD_DB_PATH": "/absolute/path/to/your/tasks.db"
      }
    }
  }
}

Omit env.TASKBOARD_DB_PATH to use the default location. Restart your MCP client after editing the config.

Running directly

npm start          # runs the built server (dist/index.js) over stdio
npm run dev         # runs src/index.ts directly via tsx, no build step

Development

npm test            # runs the test suite (node's built-in test runner + tsx)
npm run build        # type-checks and compiles src/ to dist/

License

MIT — see LICENSE.