Skip to main content
TaskForge 3.0: your AI can read your tasks.
← What's new

A local MCP server for your TaskForge vault

Shipped in version 3.0.0

Reading your vault's task format is one problem. Actually acting on it, safely, from inside a chat window, is a different one. taskforge mcp --stdio starts a small server, built into the same taskforge binary as the CLI, that speaks the Model Context Protocol so an AI client can add a task, find one, or mark it done without you copying text back and forth or trusting the model to hand-edit a markdown file.

It runs on your computer, over stdin/stdout. No server to host, no API key, no account. The only thing it talks to is the vault folder you point it at.

What it does

taskforge mcp --stdio exposes 30 tools covering the full lifecycle of a task and a note, plus a handful of utility calls:

  • Create: add_task and bulk_add_tasks create one or many tasks, optionally targeting one of your saved spaces (the space's add-recipe decides which file it lands in and what defaults get applied).
  • Read: query_tasks searches or filters with TaskForge's query language; get_task/get_tasks fetch one or many tasks by id, including the hash of their current content; read_note reads a note's body as addressable blocks.
  • Edit: update_task/bulk_update_tasks change status, priority, due date, title, or tags; patch_note_block edits one note block by its stable id, conflict-checked; update_note replaces a note's whole content, digest-guarded; patch_note_frontmatter updates selected YAML properties.
  • Lifecycle: complete_task/bulk_complete_tasks mark tasks done (if a task recurs, the response tells you the next occurrence it created); archive_task moves a task to the archive target; delete_task/ bulk_delete_tasks remove tasks. Deletes require the model to echo the task's exact current title back (confirm_title) or explicitly acknowledge a bulk delete: ids alone aren't enough, since ids can be hallucinated and a title mismatch is the cheapest way to catch it before anything is deleted.
  • Structure: move_task/bulk_move_tasks move a task to another file/section; convert_task/bulk_convert_tasks convert an inline task line to a task file and back; outdent_task/bulk_reparent_tasks promote a task relative to its parent; move_note/delete_note/ create_note rename, delete, or create any markdown file by path, updating every wikilink and reference that points at it.
  • Utility: lint_task validates a candidate line against your vault's dialect; doctor reports vault health; list_spaces enumerates your saved spaces; get_dialect reads your vault's write dialect and valid status/ priority values; normalize_references normalizes vault references.

It also exposes three resources, so an agent can read your vault's format directly instead of guessing:

  • taskforge://dialect: the same dialect data as TaskForge/Settings/dialect.json.
  • taskforge://agents-guide: the plain-language guide from TaskForge/Settings/agents.md.
  • taskforge://spaces: your saved spaces and their add-recipes.

Every call re-reads the vault from disk first. There's no cached snapshot, so if you edit a task in Obsidian or the TaskForge app while a chat is open, the next tool call sees the change.

How to install it

Install Node.js with npm and npx first. Then point your MCP client's config at npx -y taskforge-md mcp --stdio and npx fetches the taskforge-md package the first time it runs. On Windows, put cmd /c in front of that command (so the config's command is cmd with /c npx ... as arguments): desktop MCP clients start the server without a shell, and npx is a .cmd script Windows will only run through one. The snippet the app copies for you already does this. For Claude Desktop, the .mcpb bundle is a one-click alternative: download it, and Claude Desktop's guided installer walks you through picking your vault folder, no manual JSON editing required. If you built taskforge from source, point the config at the binary directly instead of npx.

Either way, you're asked for one thing during setup: the path to your vault. That gets passed to the server as TASKFORGE_VAULT, and it's the only configuration it needs.

Download the versioned native bundles from the MCP setup page. The native bundles do not require Node.js.

It needs the vault contract files

taskforge mcp --stdio reads TaskForge/Settings/dialect.json and TaskForge/Settings/agents.md to know your dialect: which checkbox syntax you use, whether priority is a symbol or a word, your renamed fields, your date format. Those files are generated automatically the first time you open a vault in TaskForge 3.0 or later (see "Your vault ships with its own AI instructions"). If a vault has never been opened in a recent TaskForge build, the server still runs, but falls back to generic defaults and warns you it's guessing.

TaskForge/Settings is the default location. If you renamed the base folder, use that folder instead.

Local, not cloud

Nothing about this feature talks to a TaskForge server, or any server. taskforge mcp --stdio reads and writes the same markdown files the app does, on the same disk. If your vault syncs through iCloud, Dropbox, or Obsidian Sync, whatever the MCP server writes syncs the same way anything else in the vault does. There's no new account to create and nothing new to trust with your data beyond the AI client you already chose to run.

Platform notes

taskforge ships as a single native binary for macOS, Windows, and Linux, with the MCP server built in as a subcommand. The TaskForge app itself runs on iOS, Android, macOS, and Windows, and any of those can generate or refresh the vault contract files the server depends on. Running the MCP server is a desktop thing, since that's where MCP clients like Claude Desktop and Claude Code live today. A vault kept in sync across your phone and your desktop stays current either way. Linux isn't an app platform, but the taskforge binary and the vault contract files work there the same as anywhere else.

Full setup guide

The durable setup guide, with install steps, the tool and resource reference, the config snippet the app copies for you, and troubleshooting, lives at taskforge.md/mcp. If you'd rather work from a terminal than an agent, the taskforge CLI covers the same vault.