Mindwtr provides an optional MCP (Model Context Protocol) server. This allows you to connect AI agents (like Claude Desktop, Claude Code, OpenAI Codex, or Gemini CLI) directly to your local Mindwtr database.

This is a local stdio server (no HTTP). MCP clients launch it as a subprocess and talk over JSON‑RPC on stdin/stdout.

Canonical reference: apps/mcp-server/README.md. Keep this page aligned with that file when MCP tools or schemas change.

• Node.js 18+ (for the MCP client that spawns the server)
• Bun (recommended for running/building the server)
• A local Mindwtr database (mindwtr.db)

• Linux: ~/.local/share/mindwtr/mindwtr.db
• macOS: ~/Library/Application Support/mindwtr/mindwtr.db
• Windows: %APPDATA%\mindwtr\mindwtr.db

You can override the database location with:

• --db /path/to/mindwtr.db
• Environment variable: MINDWTR_DB_PATH or MINDWTR_DB

MCP clients run the server as a subprocess. You point them to the command and pass arguments.

• --db "/path/to/mindwtr.db": Path to your SQLite database.
• --write: Enable write operations (add, update, complete, delete). Without this flag, the server is read-only.

Add a server entry to your Claude Desktop configuration file.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mindwtr": {
      "command": "bun",
      "args": [
        "/absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts",
        "--db",
        "/home/dd/.local/share/mindwtr/mindwtr.db",
        "--write"
      ]
    }
  }
}

Note: Replace /absolute/path/to/Mindwtr and the DB path with your actual paths.

You can add the server via the CLI:

claude mcp add mindwtr -- \
  bun /path/to/Mindwtr/apps/mcp-server/src/index.ts --db "/path/to/mindwtr.db" --write

Gemini CLI uses settings.json (User: ~/.gemini/settings.json or Project: .gemini/settings.json).

Command Line:

gemini mcp add mindwtr \
  bun /absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts \
  --db "/path/to/mindwtr.db" --write

Manual Config:

{
  "mcpServers": {
    "mindwtr": {
      "command": "bun",
      "args": [
        "/absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts",
        "--db",
        "/path/to/mindwtr.db",
        "--write"
      ]
    }
  }
}

You usually don't need to run this manually (the MCP client does it), but it's useful for testing.

# Read-only
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"

# With write access
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --write

# Build
bun run --filter mindwtr-mcp-server build

# Run
node apps/mcp-server/dist/index.js --db "/path/to/mindwtr.db"

Breaking change (introduced in this release): all tool names have changed from dot-notation (mindwtr.list_tasks) to underscore-notation (mindwtr_list_tasks) to comply with MCP client validation rules (e.g. Claude Desktop).

Old → new mapping:

Upgrade action: find and replace mindwtr. with mindwtr_ in any MCP client configs, system prompts, scripts, or automations that reference these tool names. No other changes are required.

When connected, the AI agent has access to these tools. By default the server is read-only; pass --write to enable any write tool. Only --write is supported for write access (no alternate aliases).

• mindwtr_list_tasks: List tasks with filters (status, project, date range, search).
• mindwtr_list_projects: List all projects.
• mindwtr_get_project: Get details of a specific project by ID.
• mindwtr_list_areas: List all areas.
• mindwtr_get_task: Get details of a specific task by ID.

• mindwtr_add_task: Create a new task. Supports natural language quickAdd (e.g., "Buy milk @errands /due:tomorrow").
• mindwtr_update_task: Update an existing task, including scheduling fields like dueDate, startTime, reviewAt, and isFocusedToday (supports clearing fields with null).
• mindwtr_complete_task: Mark a task as done.
• mindwtr_delete_task: Soft-delete a task.
• mindwtr_restore_task: Restore a soft-deleted task.
• mindwtr_add_project: Create a new project, including optional dueDate and reviewAt.
• mindwtr_update_project: Update a project, including optional dueDate and reviewAt.
• mindwtr_delete_project: Soft-delete a project.
• mindwtr_add_area: Create a new area.
• mindwtr_update_area: Update an area.
• mindwtr_delete_area: Soft-delete an area.

Schema note:

• Task write tools cover dueDate, startTime, and reviewAt (on update).
• Project write tools cover both dueDate and reviewAt.
• For the exact canonical inputs, use apps/mcp-server/README.md.

Use this matrix when deciding whether to run the server in read-only mode or with --write.

Practical guidance:

• Default to read-only for exploration and reporting.
• Enable --write only in trusted local environments.
• For agent workflows, prefer explicit confirmation before delete/complete operations.

1. mindwtr_list_tasks with status: "waiting" and status: "someday".
2. Summarize stalled items by project.
3. For selected items, call mindwtr_update_task to set reviewAt.

1. mindwtr_list_tasks with status: "inbox" and sortBy: "createdAt".
2. For each task, classify with mindwtr_update_task (next, waiting, reference, etc.).
3. Add missing metadata (project, contexts, tags) in a second pass.

For potentially destructive automation:

1. Run read phase: list candidate IDs only.
2. Present confirmation summary (count + titles).
3. Execute writes (complete_task / delete_task) only after explicit user approval.
4. Keep IDs for rollback via restore_task.

Use mindwtr_add_task + quickAdd:

{
  "quickAdd": "Follow up with Alex +Hiring @work #ops /due:tomorrow 10am"
}

Use this for rapid capture flows where parsing commands is more efficient than setting each field manually.

All tools return JSON in the content.text field. Parse the JSON to get the actual payload.

These limits are useful when wiring Mindwtr into agent workflows:

• mindwtr_list_tasks defaults to limit: 200 and caps limit at 500.
• Task titles are capped at 500 characters for MCP task creation/update validation.
• Quick-add inputs are capped at 2000 characters for MCP task creation, matching the cloud task API quick-add limit.
• The SQLite layer uses a busy_timeout of 5 seconds, so a locked database should fail instead of hanging indefinitely.

If you need more than 500 tasks, page with limit + offset instead of expecting one unbounded response.

Input fields

• status: inbox | next | waiting | someday | reference | done | archived | all
• projectId: string
• includeDeleted: boolean
• limit: number
• offset: number
• search: string
• dueDateFrom: ISO date or datetime string (compared by calendar date)
• dueDateTo: ISO date or datetime string (compared by calendar date)
• sortBy: updatedAt | createdAt | dueDate | title | priority
• sortOrder: asc | desc

Example

{
  "status": "next",
  "limit": 20,
  "offset": 0,
  "sortBy": "updatedAt",
  "sortOrder": "desc"
}

Response

{
  "tasks": [
    {
      "id": "task-uuid",
      "title": "Follow up with design",
      "status": "next",
      "updatedAt": "2026-01-25T03:45:57.246Z"
    }
  ]
}

Input fields

• none

Response

{
  "projects": [
    {
      "id": "project-uuid",
      "title": "Mindwtr",
      "status": "active"
    }
  ]
}

Input fields

• id: string (project UUID)
• includeDeleted: boolean (optional)

Example

{ "id": "project-uuid" }

Input fields

• none

Response

{
  "areas": [
    {
      "id": "area-uuid",
      "name": "Work"
    }
  ]
}

Input fields

• id: string (task UUID)
• includeDeleted: boolean (optional)

Example

{ "id": "task-uuid" }

Input fields

• title: string (required if quickAdd omitted)
• quickAdd: string (required if title omitted)
• status: inbox | next | waiting | someday | reference | done | archived
• projectId: string
• dueDate: ISO string
• startTime: ISO string
• contexts: string[]
• tags: string[]
• description: string
• priority: string
• timeEstimate: string (e.g. 30m, 2h)

Example

{
  "quickAdd": "Send invoice +Acme /due:tomorrow 9am #finance"
}

Input fields

• id: string (task UUID)
• title, status, projectId, dueDate, startTime, contexts, tags, description, priority, timeEstimate, reviewAt, isFocusedToday

Notes

• Use null to clear fields like projectId, dueDate, startTime, contexts, and tags.

Example

{
  "id": "task-uuid",
  "status": "waiting",
  "reviewAt": "2026-01-27T09:00:00.000Z"
}

Input fields

• id: string (task UUID)

Input fields

• id: string (task UUID)

Input fields

• id: string (task UUID)

Input fields

• title: string
• color: string (optional)
• status: active | someday | waiting | archived (optional)
• areaId: string or null
• isSequential: boolean (optional)
• isFocused: boolean (optional)
• dueDate: ISO string or null
• reviewAt: ISO string or null
• supportNotes: string or null

Input fields

• id: string (project UUID)
• title, color, status, areaId, isSequential, isFocused, dueDate, reviewAt, supportNotes

Input fields

• id: string (project UUID)

Input fields

• name: string
• color: string (optional)
• icon: string (optional)

Input fields

• id: string (area UUID)
• name, color, icon

Input fields

• id: string (area UUID)

• Tool outputs are JSON strings, not structured MCP values. Your client should parse content[0].text.
• Task/project IDs are UUIDs from the local SQLite database.
• Dates are ISO 8601 strings (UTC).

• Concurrency: The server uses SQLite WAL mode. Writes may fail if the DB is locked; clients are expected to retry.
• Shared Logic: Write operations use the shared @mindwtr/core library to ensure business rules are enforced.
• Keep-Alive: The server stays alive as long as stdin is open.

• "Command not found": mindwtr-mcp is not a global command. Use bun run mindwtr:mcp or the full path to the built script.
• Client Connection Issues: Ensure you are NOT using bun run as the command in your MCP client config, as it may output extra text. Run bun directly on the source file or node on the built file.