taskpaper-mcp-server

Model Context Protocol server for automating TaskPaper on macOS.

This server talks to TaskPaper through JavaScript for Automation (osascript -l JavaScript) and TaskPaper's document.evaluate({ script, withOptions }) bridge. It exposes a small set of safe, fixed tools rather than arbitrary TaskPaper JavaScript execution.

Requirements

• macOS
• TaskPaper installed
• Node.js 20+
• Automation permission for the MCP host to control TaskPaper

Tools

• taskpaper_status - check install/running status and open document count
• taskpaper_read_front_document - read the front document as TaskPaper text
• taskpaper_read_file - read a .taskpaper file from disk
• taskpaper_search_items - search tasks. Pass file to search a .taskpaper file directly
• taskpaper_add_task - add a task to root or a named project. Pass file to edit a .taskpaper file directly; otherwise it tries the front TaskPaper document.
• taskpaper_complete_task - mark the first matching task as @done(yyyy-mm-dd). Pass file to edit a .taskpaper file directly
• taskpaper_list_projects - list projects in a .taskpaper file
• taskpaper_archive_done - move done tasks into an archive project in a .taskpaper file
• taskpaper_set_filter - set the front document's TaskPaper filter

For reliability, prefer passing an explicit file path. TaskPaper window ordering is not stable enough to make front-document writes the primary workflow.

Development

npm install
npm test
npm run build

Run locally over stdio:

npm run build
node dist/server.js

Example MCP configuration:

{
  "mcpServers": {
    "taskpaper": {
      "command": "node",
      "args": ["/absolute/path/to/taskpaper-mcp-server/dist/server.js"]
    }
  }
}

Example direct file write:

{
  "file": "/Users/you/tasks.taskpaper",
  "project": "Inbox",
  "text": "Buy milk",
  "due": "today",
  "tags": {
    "home": true
  }
}

Humans can ask in natural language, for example "add buy milk to Inbox for today". The model should pass text, project, and friendly metadata such as due, start, or tags; the server writes valid TaskPaper tags like @due(today) into the file.

Example complete task in a file:

{
  "file": "/Users/you/tasks.taskpaper",
  "query": "Buy milk",
  "date": "2026-07-07"
}

Example archive done tasks:

{
  "file": "/Users/you/tasks.taskpaper",
  "archiveProject": "Archive"
}