mindwtr-mcp
Advanced tools
MCP server for Mindwtr. Connect MCP clients (Claude Desktop, etc.) to either your local Mindwtr SQLite database 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.
The desktop and mobile app binaries include the Mindwtr app, but they do not currently include a desktop start/stop toggle or a standalone mindwtr-mcp command on your PATH.
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.
On desktop, the app shows the exact local data path in Settings -> Sync -> Local Data. Mobile binaries do not expose a local MCP server surface.
mindwtr.db) for local mode, or a self-hosted Mindwtr Cloud URL and bearer token for Cloud modeDefault database locations:
~/.local/share/mindwtr/mindwtr.db~/Library/Application Support/mindwtr/mindwtr.db%APPDATA%\mindwtr\mindwtr.dbAdditional macOS path for sandboxed builds:
~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/mindwtr.dbIf 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.
Desktop Settings → Sync → Local Data shows the exact storage location used by the app.
You can override local mode with:
--db /path/to/mindwtr.dbMINDWTR_DB_PATH=/path/to/mindwtr.dbMINDWTR_DB=/path/to/mindwtr.dbFor self-hosted Cloud mode, use:
--cloud-url https://mindwtr.example.com or MINDWTR_MCP_CLOUD_URL--cloud-token <token> or MINDWTR_MCP_CLOUD_TOKEN--cloud-allow-insecure-http=true for trusted private HTTP deploymentsAfter 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.
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.
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 either backend (local SQLite or self-hosted Cloud).
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 <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 <host> / MINDWTR_MCP_HTTP_HOST — bind address, default 127.0.0.1.--http-port <port> / MINDWTR_MCP_HTTP_PORT — bind port, default 8722.The MCP endpoint is POST /mcp and requires Authorization: Bearer <token> on every request; GET /healthz returns 200 ok without auth for reverse-proxy health checks. Requests without a valid token get 401; bodies over 1 MiB get 413. When HTTP mode is on, the server does not also connect a stdio transport — it stays alive as long as the HTTP server is listening, not stdin.
There is no built-in TLS termination or rate limiting. If you're exposing this beyond localhost, put a reverse proxy (e.g. Caddy, nginx) in front for TLS and put the resulting https:// URL (plus your token) into the remote MCP client.
# from repo root (read-only by default)
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"
Enable writes (required for add/update/complete/delete tools):
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --write
Stop:
Ctrl+C in the terminal.The MCP server is stdio‑based. It stays alive as long as stdin is open. If your shell/client closes stdin, the process exits.
To force an immediate exit when stdin closes (no keep-alive), pass --nowait:
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --nowait
Note: When an MCP client launches the server, it keeps stdin open, so the server should remain connected.
bun run --filter mindwtr-mcp dev -- --db "/path/to/mindwtr.db"
Stop:
Ctrl+C in the terminal.# from repo root
bun run --filter mindwtr-mcp build
node apps/mcp-server/dist/index.js --db "/path/to/mindwtr.db"
Stop:
Ctrl+C in the terminal.mindwtr-mcp is “command not found”mindwtr-mcp is the package binary. It exists after installing the npm package globally, after an MCP client launches it through npx, or after you build the source package and run it with Node.
Use one of these source-tree options instead:
# ✅ works immediately
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"
# ✅ build then run
bun run --filter mindwtr-mcp build
node apps/mcp-server/dist/index.js --db "/path/to/mindwtr.db"
mindwtr-mcp commandIf you want a real mindwtr-mcp command on your PATH, create a tiny wrapper:
cat > ~/bin/mindwtr-mcp <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd /absolute/path/to/Mindwtr
exec bun run mindwtr:mcp -- "$@"
EOF
chmod +x ~/bin/mindwtr-mcp
Then use:
mindwtr-mcp --db "/path/to/mindwtr.db"
Not yet. Start/stop is still manual.
MCP clients run the server as a subprocess. You point them to the command and pass args/env.
Important: Do NOT use bun run mindwtr:mcp for MCP clients. The bun run wrapper outputs shell messages to stdout (e.g., $ bun run --filter...) which breaks the JSON-RPC protocol. Always run bun directly on the source file.
{
"mcpServers": {
"mindwtr": {
"command": "bun",
"args": [
"/absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts",
"--db",
"~/.local/share/mindwtr/mindwtr.db"
]
}
}
}
Add --write to the args if you want to enable add/update/complete/delete tools.
If your client doesn't support Bun, build first and use Node:
# Build once
cd /path/to/Mindwtr && bun run --filter mindwtr-mcp build
{
"mcpServers": {
"mindwtr": {
"command": "node",
"args": [
"/absolute/path/to/Mindwtr/apps/mcp-server/dist/index.js",
"--db",
"~/.local/share/mindwtr/mindwtr.db"
]
}
}
}
Add --write to the args if you want to enable add/update/complete/delete tools.
Claude Desktop supports MCP (stdio). Add a server entry in its MCP configuration.
Typical config file locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonAfter editing, fully quit and relaunch Claude Desktop.
Add a server via the CLI:
claude mcp add mindwtr -- \
bun /path/to/Mindwtr/apps/mcp-server/src/index.ts --db "/path/to/mindwtr.db" --write
Or edit ~/.claude.json directly:
{
"projects": {
"/path/to/your/project": {
"mcpServers": {
"mindwtr": {
"type": "stdio",
"command": "bun",
"args": [
"/absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts",
"--db",
"~/.local/share/mindwtr/mindwtr.db",
"--write"
]
}
}
}
}
}
Then restart the Claude Code session and run /mcp to verify it's connected.
Codex stores MCP config in ~/.codex/config.toml. Add:
[mcp_servers.mindwtr]
command = "bun"
args = ["/absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts", "--db", "/path/to/mindwtr.db", "--write"]
# Optional: pass env vars to the server
[mcp_servers.mindwtr.env]
MINDWTR_DB_PATH = "/path/to/mindwtr.db"
Restart Codex after saving.
Gemini CLI uses a JSON settings.json with mcpServers, either:
~/.gemini/settings.json.gemini/settings.json in your repoYou can add Mindwtr MCP two ways:
1) CLI (recommended):
gemini mcp add mindwtr \
bun /absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts \
--db "/path/to/mindwtr.db" --write
2) Edit settings.json manually:
{
"mcpServers": {
"mindwtr": {
"command": "bun",
"args": ["/absolute/path/to/Mindwtr/apps/mcp-server/src/index.ts", "--db", "/path/to/mindwtr.db", "--write"]
}
}
}
Restart the Gemini CLI session after saving.
Any MCP-compatible client can work as long as it can launch a stdio server with the command + args above.
mindwtr.* → mindwtr_*)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:
| Old name | New name |
|---|---|
mindwtr.list_tasks | mindwtr_list_tasks |
mindwtr.list_projects | mindwtr_list_projects |
mindwtr.get_project | mindwtr_get_project |
mindwtr.get_task | mindwtr_get_task |
mindwtr.list_areas | mindwtr_list_areas |
mindwtr.add_task | mindwtr_add_task |
mindwtr.update_task | mindwtr_update_task |
mindwtr.complete_task | mindwtr_complete_task |
mindwtr.delete_task | mindwtr_delete_task |
mindwtr.restore_task | mindwtr_restore_task |
mindwtr.add_project | mindwtr_add_project |
mindwtr.update_project | mindwtr_update_project |
mindwtr.delete_project | mindwtr_delete_project |
mindwtr.add_area | mindwtr_add_area |
mindwtr.update_area | mindwtr_update_area |
mindwtr.delete_area | mindwtr_delete_area |
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.
mindwtr_list_tasks
{ status?, projectId?, includeDeleted?, limit?, offset?, search?, dueDateFrom?, dueDateTo?, sortBy?, sortOrder? }mindwtr_list_projects
{}mindwtr_get_project
{ id, includeDeleted? }mindwtr_list_sections
{ projectId?, includeDeleted? }mindwtr_get_section
{ id, includeDeleted? }mindwtr_list_areas
{}mindwtr_list_people
{ includeDeleted? }mindwtr_get_person
{ id, includeDeleted? }mindwtr_get_task
{ id, includeDeleted? }mindwtr_add_task (requires --write)
{ title? | quickAdd?, status?, projectId?, sectionId?, dueDate?, startTime?, recurrence?, contexts?, tags?, description?, priority?, timeEstimate? }mindwtr_update_task (requires --write)
{ id, title?, status?, projectId?, sectionId?, dueDate?, startTime?, recurrence?, contexts?, tags?, description?, priority?, timeEstimate?, reviewAt?, isFocusedToday? }recurrence accepts a recurrence object or an RFC 5545 RRULE string. Pass null to clear it.mindwtr_complete_task (requires --write)
{ id }mindwtr_delete_task (requires --write)
{ id }mindwtr_restore_task (requires --write)
{ id }mindwtr_add_project (requires --write)
{ title, color?, status?, areaId?, isSequential?, isFocused?, dueDate?, reviewAt?, supportNotes? }mindwtr_update_project (requires --write)
{ id, title?, color?, status?, areaId?, isSequential?, isFocused?, dueDate?, reviewAt?, supportNotes? }mindwtr_delete_project (requires --write)
{ id }mindwtr_add_section (requires --write)
{ projectId, title, description?, order?, isCollapsed? }mindwtr_update_section (requires --write)
{ id, title?, description?, order?, isCollapsed? }mindwtr_delete_section (requires --write)
{ id }mindwtr_add_area (requires --write)
{ name, color?, icon? }mindwtr_update_area (requires --write)
{ id, name?, color?, icon? }mindwtr_delete_area (requires --write)
{ id }mindwtr_add_person (requires --write)
{ name, note?, referenceLink? }mindwtr_update_person (requires --write)
{ id, name?, note?, referenceLink? }mindwtr_rename_person (requires --write)
{ id, name, updateTasks? }mindwtr_delete_person (requires --write)
{ id }All tools return JSON text payloads with the resulting task, project, section, area, person, or collection payload.
bun run mindwtr:mcp -- --db "~/.local/share/mindwtr/mindwtr.db"
mindwtr_list_tasks (limit 5)If you want to test writes, restart with --write:
bun run mindwtr:mcp -- --db "~/.local/share/mindwtr/mindwtr.db" --write
Then test:
mindwtr_add_task (quickAdd: "Test task @home /due:tomorrow")mindwtr_complete_task (use returned task id)mindwtr_update_task (e.g. set status or dueDate)mindwtr_delete_task (use returned task id)mindwtr_get_task (use returned task id)mindwtr_restore_task (after delete, restore the task)mindwtr_list_projectsmindwtr_get_project (use returned project id)mindwtr_list_areasmindwtr_list_peoplemindwtr_add_projectmindwtr_update_projectmindwtr_delete_projectmindwtr_add_areamindwtr_update_areamindwtr_delete_areamindwtr_add_personmindwtr_update_personmindwtr_rename_personmindwtr_get_person (use returned person id)mindwtr_delete_personmindwtr_list_tasks with dueDateFrom, dueDateTo, sortBy, sortOrderIf the list returns tasks and add/complete works, the server is healthy.
Use any MCP client or a small script to send:
initializenotifications/initializedtools/listtools/call (e.g. mindwtr_list_projects or mindwtr_list_tasks)If these succeed, the stdio transport is working end-to-end.
claude mcp add mindwtr -- \
bun /path/to/Mindwtr/apps/mcp-server/src/index.ts --db "/path/to/mindwtr.db" --write
/mcp, and verify mindwtr is connected.mindwtr_list_tasks (limit 5)mindwtr_add_task (quickAdd: "Test MCP @home /due:tomorrow")mindwtr_complete_task (use returned id)--write to enable edits.@mindwtr/core.FAQs
Stdio MCP server for Mindwtr local and self-hosted Cloud task access.
The npm package mindwtr-mcp receives a total of 452 weekly downloads. As such, mindwtr-mcp popularity was classified as not popular.
We found that mindwtr-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.