Mindwtr

Mindwtr MCP Server

MCP server for Mindwtr. Connect MCP clients (Claude Desktop, etc.) to your local SQLite database, the desktop Local API, or a self-hosted Mindwtr Cloud endpoint.

By default this is a stdio server: MCP clients launch it as a subprocess and talk over JSON-RPC on stdin/stdout. It also has an opt-in HTTP transport (see Remote access (HTTP)) for self-hosters who want to expose it at a URL instead.

---

App Binaries vs. MCP Helper

The desktop app includes a built-in MCP server in Settings → Integrations → Local MCP server (advanced). It requires no separately installed runtime or helper. The desktop installer does not add a standalone mindwtr-mcp command to your PATH; mobile apps do not host MCP.

You do not need to run the whole app from source to use MCP. You can use the normal desktop app binary for your tasks, then run this separate MCP helper from the repository with Bun, or build the helper once and run it with Node. Point the helper at the desktop app's local mindwtr.db, or use the Local API backend below.

On desktop, find the database in the default database locations listed under Requirements. Mobile binaries do not expose a local MCP server surface.

---

Requirements

These requirements apply to the standalone helper, not the built-in desktop server.

• Node.js 20+ to run the helper. Prefer Node.js 22+ for prebuilt SQLite binaries on supported platforms; Node 20 requires a native build toolchain.
• Node-based SQLite mode uses the optional better-sqlite3 native addon. API-only installs can omit it with --omit=optional. If no prebuilt binary is available for your platform, npm needs a working C/C++ build toolchain and Python for node-gyp.
• Bun (recommended for development in this repo)
• A local database (mindwtr.db) for SQLite mode, a running desktop Local API and bearer token for API mode, or a self-hosted Mindwtr Cloud URL and bearer token for Cloud mode

For SQLite mode with npm 12, approve the SQLite dependency's install script; otherwise a successful install can still fail at startup with a missing native binding. For npx or global installs, allow only better-sqlite3:

npx --allow-scripts=better-sqlite3 -y mindwtr-mcp --db "/path/to/mindwtr.db"

npm install -g --allow-scripts=better-sqlite3 mindwtr-mcp

In MCP client configurations using npx, add "--allow-scripts=better-sqlite3" before "mindwtr-mcp" in args. For an existing project-local install, run npm install-scripts approve better-sqlite3, then npm rebuild better-sqlite3 from that project. Review the dependency before approving; do not enable all dependency scripts.

Default database locations. The installed Windows and macOS apps keep the database in a data subfolder from version 1.3.2 on; Linux and the portable builds are unchanged. The server looks in both places, so it finds the database either way.

• Linux: ~/.local/share/mindwtr/mindwtr.db (Flatpak: ~/.var/app/tech.dongdongbh.mindwtr/data/mindwtr/mindwtr.db; Snap: ~/snap/mindwtr/current/.local/share/mindwtr/mindwtr.db)
• macOS, 1.3.2 and later: ~/Library/Application Support/mindwtr/data/mindwtr.db
• macOS, 1.3.1 and earlier: ~/Library/Application Support/mindwtr/mindwtr.db
• Windows, 1.3.2 and later: %APPDATA%\mindwtr\data\mindwtr.db
• Windows, 1.3.1 and earlier: %APPDATA%\mindwtr\mindwtr.db

Additional macOS paths for sandboxed builds:

• 1.3.2 and later: ~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/data/mindwtr.db
• 1.3.1 and earlier: ~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/mindwtr.db

A --db path pinned in an MCP client configuration keeps working across that move: if the file is not at the configured path, the server checks the matching data subfolder (or the parent folder) and reports on stderr which database it opened.

If mindwtr.db is missing but data.json exists in the same desktop data folder, the MCP server will bootstrap a fresh SQLite database from that local data snapshot on first start. The desktop data folder is the folder that holds mindwtr.db in the default locations above.

You can override local mode with:

• --db /path/to/mindwtr.db
• MINDWTR_DB_PATH=/path/to/mindwtr.db
• MINDWTR_DB=/path/to/mindwtr.db

For self-hosted Cloud mode, use:

• --cloud-url https://mindwtr.example.com or MINDWTR_MCP_CLOUD_URL
• --cloud-token or MINDWTR_MCP_CLOUD_TOKEN
• optional --cloud-allow-insecure-http=true for trusted private HTTP deployments

---

Start / Stop

Run from npm

After installing the published package, run it directly:

mindwtr-mcp --db "/path/to/mindwtr.db"

Or let an MCP client launch it through npx:

{

"mcpServers": { "mindwtr": { "command": "npx", "args": [ "-y", "mindwtr-mcp", "--db", "~/.local/share/mindwtr/mindwtr.db" ] } } }

The npm package is read-only by default. Add --write only when you explicitly want add/update/complete/delete tools enabled.

Desktop Local API mode

Requires mindwtr-mcp 1.1.11 or later.

Enable the desktop app's Local API in Settings and copy its bearer token. Keep the app and API running. This backend uses the app's REST endpoints and never opens a database or falls back to SQLite.

For an API-only installation, omit the optional native SQLite addon:

npm install -g --omit=optional mindwtr-mcp

Configure your MCP client to pass the token through its environment, rather than putting it in command-line arguments:

{

"command": "mindwtr-mcp", "args": ["--api-url", "http://127.0.0.1:3456"], "env": { "MINDWTR_MCP_API_TOKEN": " " } }

Use the port shown in Settings. MINDWTR_MCP_API_URL can replace --api-url. URLs must use literal 127.0.0.1 or [::1], with no credentials, path, query or fragment; redirects are refused. Do not combine API and Cloud/--db options. Existing database-path environment variables are ignored in API mode.

Writes remain disabled unless explicitly enabled with --write. If the app is closed or the token is invalid, the helper returns an error. A timed-out write may have reached the app: inspect the task before retrying, as the helper does not retry writes automatically.

Desktop 1.3.8 adds optional protection for task creation and edits in Local API mode:

• mindwtr_add_task accepts idempotencyKey, 1–128 visible ASCII characters without spaces. Keep the same key and identical input when retrying an uncertain create, including attachment links. The desktop retains the original result for seven days, even if that task is later edited or deleted. Different input with the same key returns idempotency_conflict. A full receipt store returns idempotency_capacity; retry later with the same key and input.
• mindwtr_get_task, task creation, and task edits return { "task": { ... }, "version": "sha256-..." }. Pass the version unchanged as expectedVersion to mindwtr_update_task. A stale edit returns task_version_conflict; read the task again and review the changes before retrying. An edit that changes nothing preserves the version.

Both arguments are optional. Without them, writes keep their existing behavior. Protected requests use versioned desktop endpoints and fail on older desktop versions without falling back to an unprotected write. Older desktop reads can omit version. These arguments are unavailable in Cloud and direct SQLite mode; unsupported task input fields are rejected. Attachment replacement and lifecycle restrictions below still apply.

Other unsupported fields are rejected before a write. The desktop API's recurrence limitations also apply; some recurring completions must be performed in the app. This backend does not promise full SQLite/Cloud tool parity.

--api-url selects the helper's data source. --http instead selects how an MCP client connects to the helper; it can be used with any backend and has a separate authentication token.

Self-hosted Cloud mode

Use Cloud mode when you run your own Mindwtr Cloud server and want MCP tools without pointing the helper at a local SQLite database:

npx -y mindwtr-mcp \

--cloud-url "https://mindwtr.example.com" \ --cloud-token "$MINDWTR_TOKEN"

Or pass the same values through environment variables:

MINDWTR_MCP_CLOUD_URL="https://mindwtr.example.com" \

MINDWTR_MCP_CLOUD_TOKEN="$MINDWTR_TOKEN" \ npx -y mindwtr-mcp

Cloud mode uses the self-hosted Cloud API. Reads come from the current /v1/data snapshot; with --write, task/project/section/area writes go through the Cloud server's per-resource REST endpoints (POST /v1/tasks, PATCH /v1/tasks/:id, and so on), so they get the same validation and revision stamping as any other client. Without --write, write tools return read_only. Person edits and restoring deleted tasks are not available in Cloud mode yet.

This does not make Mindwtr Cloud itself a hosted MCP server. It is still the same stdio helper, backed by a Cloud URL that you operate.

For private HTTP test deployments, local/private HTTP URLs are allowed by the shared Cloud client rules. Use --cloud-allow-insecure-http=true only for a self-hosted endpoint you intentionally trust.

Remote access (HTTP)

By default mindwtr-mcp only speaks stdio. Pass --http to also (instead of stdio) serve a stateless streamable-HTTP MCP endpoint, so you can point a remote MCP client at a URL — the motivating case is Gemini Spark "custom apps", which take an MCP server URL. HTTP mode works with all three backends.

mindwtr-mcp --http --http-token "$(openssl rand -hex 32)" --db "/path/to/mindwtr.db"

Flags (all have MINDWTR_MCP_HTTP* env var equivalents):

• --http / MINDWTR_MCP_HTTP — enable HTTP mode. Also implied by setting --http-host, --http-port, or --http-token.
• --http-token / MINDWTR_MCP_HTTP_TOKEN — required whenever HTTP mode is on, at least 16 characters. Generate one with openssl rand -hex 32. The server refuses to start without it — there is no way to expose HTTP mode unauthenticated, even on loopback.
• --http-host / MINDWTR_MCP_HTTP_HOST — bind address, default 127.0.0.1.
• --http-port / MINDWTR_MCP_HTTP_PORT — bind port, default 8722.

The desktop app's built-in MCP server also uses port 8722. If it is on, pass another port with --http-port, for example --http-port 8723.

The MCP endpoint is POST /mcp and requires Authorization: Bearer on every request; GET /healthz returns 200 ok without auth for reverse-proxy health checks. Requests without a valid token get 401; repeated authentication failures get 429 with a Retry-After header. Bodies over 1 MiB get 413. When HTTP mode is on, the server does not also connect a stdio transport — it