Mindwtr

Mindwtr MCP サーバー

Mindwtr 用の MCP サーバーです。MCP クライアント（Claude Desktop など）を、ローカルの SQLite データベース、デスクトップの Local API、またはセルフホストの Mindwtr Cloud エンドポイントに接続します。

デフォルトでは stdio サーバーです。MCP クライアントがサブプロセスとして起動し、stdin/stdout を介して JSON-RPC で通信します。また、URL で公開したいセルフホストユーザー向けに、オプトイン方式の HTTP トランスポート（リモートアクセス（HTTP）を参照）も用意されています。

---

アプリのバイナリと MCP ヘルパー

デスクトップアプリには、Settings → Integrations → Local MCP server (advanced) に組み込みの MCP サーバーがあります。別途ランタイムやヘルパーをインストールする必要はありません。デスクトップインストーラーは、スタンドアロンの mindwtr-mcp コマンドを PATH に追加しません。モバイルアプリは MCP をホストしません。

MCP を使用するために、アプリ全体をソースから実行する必要はありません。通常のデスクトップアプリのバイナリでタスクを行い、リポジトリから Bun でこの別個の MCP ヘルパーを実行するか、ヘルパーを一度ビルドして Node で実行できます。ヘルパーの接続先には、デスクトップアプリのローカル mindwtr.db を指定するか、以下の Local API バックエンドを使用してください。

デスクトップでは、要件に記載されているデフォルトのデータベース保存場所でデータベースを確認できます。モバイル版のバイナリは、ローカル MCP サーバーの機能を公開しません。

---

要件

これらの要件は、組み込みのデスクトップサーバーではなく、スタンドアロンのヘルパーに適用されます。

• ヘルパーの実行には Node.js 20 以降が必要です。サポート対象のプラットフォームで SQLite のビルド済みバイナリを利用するには、Node.js 22 以降を推奨します。Node 20 ではネイティブビルドツールチェーンが必要です。
• Node ベースの SQLite モードでは、オプションのネイティブアドオンである better-sqlite3 を使用します。API のみのインストールでは、--omit=optional を指定して省略できます。お使いのプラットフォームでビルド済みバイナリを利用できない場合、npm で node-gyp を実行するには、動作する C/C++ ビルドツールチェーンと Python が必要です。
• Bun（このリポジトリでの開発に推奨）
• SQLite モードではローカルデータベース（mindwtr.db）、API モードでは実行中のデスクトップ Local API とベアラートークン、Cloud モードではセルフホスト可能な Mindwtr Cloud の URL とベアラートークン

npm 12 で SQLite モードを使用する場合、SQLite 依存関係のインストールスクリプトを許可してください。許可しないと、インストールが成功しても、ネイティブバインディングが見つからず起動に失敗することがあります。npx またはグローバルインストールの場合は、better-sqlite3 のみを許可してください。

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

npx を使用する MCP クライアントの設定では、args 内の "mindwtr-mcp" より前に "--allow-scripts=better-sqlite3" を追加してください。既存のプロジェクトローカルインストールでは、npm install-scripts approve better-sqlite3 を実行してから、そのプロジェクトで npm rebuild better-sqlite3 を実行してください。許可する前に依存関係を確認し、すべての依存関係スクリプトを有効にしないでください。

データベースのデフォルトの場所。インストール済みの Windows および macOS アプリでは、バージョン 1.3.2 以降、データベースは data サブフォルダーに保存されます。Linux とポータブル版に変更はありません。サーバーは両方の場所を検索するため、どちらにあってもデータベースを見つけます。

• 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 以降：~/Library/Application Support/mindwtr/data/mindwtr.db
• macOS、1.3.1 以前：~/Library/Application Support/mindwtr/mindwtr.db
• Windows、1.3.2 以降：%APPDATA%\mindwtr\data\mindwtr.db
• Windows、1.3.1 以前：%APPDATA%\mindwtr\mindwtr.db

サンドボックス化されたビルドでの macOS の追加パス：

• 1.3.2 以降：~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/data/mindwtr.db
• 1.3.1 以前：~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/mindwtr.db

MCP クライアントの設定で指定した --db パスは、この移動後も引き続き使用できます。設定したパスにファイルがない場合、サーバーは対応する data サブフォルダー（または親フォルダー）を確認し、どのデータベースを開いたかを stderr に表示します。

mindwtr.db が見つからず、同じデスクトップデータフォルダーに data.json がある場合、MCP サーバーは初回起動時に、そのローカルデータスナップショットから新しい SQLite データベースを作成します。 デスクトップデータフォルダーとは、上記のデフォルトの場所にある mindwtr.db が保存されているフォルダーです。

ローカルモードは、次の方法で上書きできます。

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

セルフホスト可能な Cloud モードでは、次を使用します。

• --cloud-url https://mindwtr.example.com または MINDWTR_MCP_CLOUD_URL
• --cloud-token <token> または MINDWTR_MCP_CLOUD_TOKEN
• 信頼できるプライベート HTTP 環境でのデプロイでは、任意で --cloud-allow-insecure-http=true

---

起動／停止

npm から実行

公開済みのパッケージをインストールした後、次のコマンドで直接実行します。

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

または、MCP クライアントから npx 経由で起動できます。

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

npm パッケージはデフォルトで読み取り専用です。追加／更新／完了／削除ツールを有効にする場合に限り、--write を追加してください。

デスクトップのローカル API モード

mindwtr-mcp 1.1.11 以降が必要です。

設定でデスクトップアプリの ローカル API を有効にし、Bearer トークンをコピーします。アプリと API は起動したままにしてください。このバックエンドはアプリの REST エンドポイントを使用し、データベースを開いたり、SQLite にフォールバックしたりすることはありません。

API のみを使用するインストールでは、オプションのネイティブ SQLite アドオンを省略します。

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

トークンはコマンドライン引数に含めず、環境変数を通じて渡すよう MCP クライアントを設定します。

{
  "command": "mindwtr-mcp",
  "args": ["--api-url", "http://127.0.0.1:3456"],
  "env": {
    "MINDWTR_MCP_API_TOKEN": "<token from desktop settings>"
  }
}

設定に表示されているポートを使用します。MINDWTR_MCP_API_URL を使って --api-url を置き換えることもできます。URL には 127.0.0.1 または [::1] をそのまま指定し、認証情報、パス、クエリ、フラグメントを含めないでください。リダイレクトは拒否されます。API オプションと Cloud／--db オプションを併用しないでください。既存のデータベースパス環境変数は API モードでは無視されます。

書き込みは --write を明示的に有効にしない限り無効です。アプリが終了している場合やトークンが無効な場合、ヘルパーはエラーを返します。タイムアウトした書き込みがアプリに反映されている可能性があります。ヘルパーは書き込みを自動で再試行しないため、再試行する前にタスクを確認してください。

MCP の機能	デスクトップのローカル API の対応状況
タスクの一覧表示／取得	リッチな検索演算子、日付フィルター、並べ替え、ページネーションを含めて対応しています
タスクの作成	明示的なタイトルとフィールドに対応しています。quickAdd は利用できません
タスクの更新／完了／削除／復元	API の対応するエンドポイントを通じて対応しています。ターミナルステータスの変更は通常の編集として送信できません
プロジェクトの一覧表示／取得／作成／更新／削除	API の基本的なプロジェクトフィールド（タイトル、色、ステータス、エリア、連番動作）に対応しています
エリアの一覧表示	対応しています
セクションカタログとプロジェクトの割り当ての表示	利用できません。既知の ID によるタスクの割り当てには対応しています
セクション、管理対象の人物、エリアへの書き込み	利用できません。これらのツールは API モードでは非表示になります
GTD の利用可能性 view	API が必要なセクションスナップショットを公開していないため、利用できません
添付ファイルリンクの置き換え	API が条件付き添付ファイル更新を提供していないため、利用できません

その他の未対応フィールドは、書き込みの前に拒否されます。デスクトップ API の繰り返しに関する制限も適用されます。繰り返しタスクの完了処理は、アプリで行う必要がある場合があります。このバックエンドは、SQLite／Cloud のツールとの完全な同等性を保証しません。

--api-url はヘルパーのデータソースを選択します。一方、--http は MCP クライアントがヘルパーに接続する方法を選択します。--http はどのバックエンドでも使用でき、別個の認証トークンを使用します。

セルフホスト Cloud モード

独自の Mindwtr Cloud サーバーを実行していて、ヘルパーをローカル SQLite データベースに接続せずに MCP ツールを使いたい場合は、Cloud モードを使用します。

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

同じ値を環境変数で渡すこともできます。

MINDWTR_MCP_CLOUD_URL="https://mindwtr.example.com" \
MINDWTR_MCP_CLOUD_TOKEN="$MINDWTR_TOKEN" \
npx -y mindwtr-mcp

Cloud モードはセルフホストの Cloud API を使用します。読み取りは現在の /v1/data スナップショットから行われます。--write を指定すると、タスク／プロジェクト／セクション／エリアの書き込みは、Cloud サーバーのリソースごとの REST エンドポイント（POST /v1/tasks、PATCH /v1/tasks/:id など）を通じて行われるため、他のクライアントと同じ検証とリビジョンの記録が適用されます。--write を指定しない場合、書き込みツールは read_only を返します。人物の編集と削除済みタスクの復元は、Cloud モードではまだ利用できません。

これは Mindwtr Cloud 自体をホスト型 MCP サーバーにするものではありません。Cloud の URL をバックエンドとして使用する同じ標準入出力ヘルパーです。

プライベートな HTTP テスト環境では、共有 Cloud クライアントのルールに従って、ローカル／プライベート HTTP URL が許可されます。--cloud-allow-insecure-http=true は、意図的に信頼しているセルフホストのエンドポイントに限って使用してください。

リモートアクセス（HTTP）

デフォルトでは、mindwtr-mcp は stdio のみを使用します。--http を渡すと、ステートレスなストリーマブル HTTP MCP エンドポイントを（stdio の代わりに）提供するようになり、URL をリモート MCP クライアントに指定できます。想定されている用途は、MCP サーバーの URL を指定する Gemini Spark の「カスタムアプリ」です。HTTP モードは 3 つすべてのバックエンドで動作します。

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

フラグ（すべて MINDWTR_MCP_HTTP* に対応する環境変数があります）：

• --http / MINDWTR_MCP_HTTP — HTTP モードを有効にします。--http-host、--http-port、--http-token のいずれかを設定した場合も有効になります。
• --http-token <token> / MINDWTR_MCP_HTTP_TOKEN — HTTP モードが有効な場合は必須で、16 文字以上である必要があります。openssl rand -hex 32 で生成できます。トークンがないとサーバーは起動しません。ループバック上であっても、認証なしで HTTP モードを公開する方法はありません。
• --http-host <host> / MINDWTR_MCP_HTTP_HOST — バインドアドレスです。デフォルトは 127.0.0.1 です。
• --http-port <port> / MINDWTR_MCP_HTTP_PORT — バインドポートです。デフォルトは 8722 です。

デスクトップアプリに組み込まれた MCP サーバーもポート 8722 を使用します。起動中の場合は、--http-port 8723 のように別のポートを --http-port で指定してください。

MCP エンドポイントは POST /mcp で、すべてのリクエストに Authorization: Bearer <token> が必要です。GET /healthz は、リバースプロキシのヘルスチェック用に、認証なしで 200 ok を返します。有効なトークンがないリクエストには 401 が返されます。認証に繰り返し失敗すると、Retry-After ヘッダー付きで 429 が返されます。1 MiB を超える本文には 413 が返されます。HTTP モードが有効な場合、サーバーは stdio トランスポートにも接続しません。サーバーは stdin ではなく、HTTP サーバーがリッスンしている限り稼働します。

認証済みリクエストに対する組み込みの TLS 終端やレート制限はありません。localhost の外部に公開する場合は、TLS を使用できるよう Caddy や nginx などのリバースプロキシを前段に配置し、生成された https:// URL とトークンをリモート MCP クライアントに設定してください。

リポジトリから直接実行する

# from repo root (read-only by default)
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"

書き込みを有効にします（追加／更新／完了／削除ツールで必要です）：

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

停止するには：

• ターミナルで Ctrl+C を押します。

キープアライブの動作（終了することがある理由）

MCP サーバーはstdio ベースです。stdin が開いている限り稼働します。 シェルまたはクライアントが stdin を閉じると、プロセスは終了します。

stdin が閉じたときにすぐ終了させる（キープアライブしない）には、--nowait を渡します：

bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --nowait

注：MCP クライアントがサーバーを起動すると、stdin を開いたままにするため、サーバーは接続された状態を保ちます。

ヘルパースクリプトを使わずに実行する

bun run --filter mindwtr-mcp dev -- --db "/path/to/mindwtr.db"

停止するには：

• ターミナルで Ctrl+C を押します。

バイナリエントリ（Node）のビルドと実行

# from repo root
bun run --filter mindwtr-mcp build
node apps/mcp-server/dist/cli.js --db "/path/to/mindwtr.db"

停止するには：

• ターミナルで Ctrl+C を押します。

---

mindwtr-mcp が「コマンドが見つかりません」となる理由

mindwtr-mcp はパッケージのバイナリです。npm パッケージをグローバルにインストールした後、MCP クライアントが npx 経由で起動した後、またはソースパッケージをビルドして Node で実行した後に利用できます。

代わりに、次のソースツリーでの方法を使用してください：

# ✅ 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/cli.js --db "/path/to/mindwtr.db"

オプション：グローバルな mindwtr-mcp コマンドを作成する

PATH 上で実際の mindwtr-mcp コマンドを使いたい場合は、簡単なラッパーを作成します：

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

次に、以下を実行します：

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

デスクトップアプリの切り替え

デスクトップアプリには、**設定 → インテグレーション → ローカル MCP サーバー（詳細）**があります。アクセスはデフォルトで無効になっており、読み取り専用です。有効にして、認証付き Streamable HTTP に対応するクライアント向けの接続情報をコピーします。デフォルトのエンドポイントは http://127.0.0.1:8722/mcp です。詳細では、1024〜65535 の範囲でポートを選択できます。ポートを保存してから、クライアントの接続情報を更新してください。サーバーは引き続きループバックにバインドされます。

v1.3.7 以降では、タスクとプロジェクトの編集を許可すると、タスクの作成、編集、完了、復元と、プロジェクトの作成または編集が可能になります。詳細には、個別のアーカイブを許可および削除を許可の権限があります。各権限は独立しており、新規インストールではすべて無効です。変更を許可を有効にしていた既存のインストールでは、以前の削除権限が維持されます。この権限は現在、個別に無効にできます。アーカイブには、新たに明示的な許可が必要です。通常の編集とアーカイブ／キャンセルの変更を組み合わせた更新には、両方の権限が必要です。専用の mindwtr_archive_task ツールは、タスクを完了したり、繰り返しタスクを生成したりせずに、アプリのアーカイブ操作を実行します。削除は引き続き論理削除です。

Codex 用にコピーすると、~/.codex/config.toml 用の TOML が提供されます。他の設定を保持したまま、mcp_servers.mindwtr エントリを追加または置き換えてください。Mindwtr がそのファイルを編集することはありません。接続情報をコピーすると、mcpServers を使用するクライアント向けに JSON 形式が保持されます。どちらにもプライベートなベアラートークンが含まれます。接続された AI クライアントは、公開されている Mindwtr のデータを読み取り、プロバイダーに送信する場合があります。トークンを再生成すると、古いクライアントは切断されます。

組み込みサーバーはデスクトップアプリ内で実行され、タスクとプロジェクトの操作をローカル API と共有します。ローカル API を有効にする必要はありません。トレイに最小化して閉じても実行は継続されますが、MCP を無効にするかアプリを終了すると停止します。起動失敗またはポート使用中の場合は、設定に「再試行」が表示されます。このモードでは、リモート ChatGPT アクセス、トンネル、ホスティングは提供されません。スタンドアロンヘルパーのバックエンド固有の機能と --write フラグは、これらのデスクトップ権限とは別のものです。

ソースからビルドする場合、組み込みサーバーはデスクトップの Rust アプリケーションとともにコンパイルされます。個別の MCP 実行ファイルやランタイムは同梱されません。

---

MCP クライアントの設定

MCP クライアントは、サーバーをサブプロセスとして実行します。コマンドを指定し、引数／環境変数を渡してください。

重要： MCP クライアントでは bun run mindwtr:mcp を使用しないでください。bun run のラッパーは stdout にシェルメッセージ（例：$ bun run --filter...）を出力するため、JSON-RPC プロトコルが壊れます。必ず bun からソースファイルを直接実行してください。

例（汎用 MCP 設定）

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

追加／更新／完了／削除ツールを有効にする場合は、引数に --write を追加してください。

クライアントが Bun に対応していない場合は、先にビルドしてから 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/cli.js",
        "--db",
        "~/.local/share/mindwtr/mindwtr.db"
      ]
    }
  }
}

追加／更新／完了／削除ツールを有効にする場合は、引数に --write を追加してください。

Claude Desktop

Claude Desktop は MCP（stdio）に対応しています。MCP 設定にサーバーエントリを追加してください。

一般的な設定ファイルの場所：

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

編集後、Claude Desktop を完全に終了してから再起動してください。

Claude Code（CLI）

CLI からサーバーを追加します。

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

または、~/.claude.json を直接編集します。

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "mindwtr": {
          "type": "stdio",
          "command": "bun",
          "args": [
            "/absolute/path/to/Mindwtr/apps/mcp-server/src/cli.ts",
            "--db",
            "~/.local/share/mindwtr/mindwtr.db",
            "--write"
          ]
        }
      }
    }
  }
}

その後、Claude Code のセッションを再起動し、/mcp を実行して接続を確認してください。

OpenAI Codex（config.toml）

Codex は MCP 設定を ~/.codex/config.toml に保存します。以下を追加してください。

[mcp_servers.mindwtr]
command = "bun"
args = ["/absolute/path/to/Mindwtr/apps/mcp-server/src/cli.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"

保存後、Codex を再起動してください。

Gemini CLI

Gemini CLI は、mcpServers を含む JSON の settings.json を使用します。設定場所は次のいずれかです。

• ユーザースコープ：~/.gemini/settings.json
• プロジェクトスコープ：リポジトリ内の .gemini/settings.json

Mindwtr MCP は次の 2 つの方法で追加できます。

1) CLI（推奨）：

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

2) settings.json を手動で編集：

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

保存後、Gemini CLI のセッションを再起動してください。

その他の MCP クライアント

上記のコマンドと引数を使って stdio サーバーを起動できれば、どの MCP 互換クライアントでも動作します。

---

移行：ツール名の変更（mindwtr.* → mindwtr_*）

破壊的変更（このリリースで導入）：MCP クライアントの検証ルール（例：Claude Desktop）に準拠するため、すべてのツール名がドット表記（mindwtr.list_tasks）からアンダースコア表記（mindwtr_list_tasks）に変更されました。

旧名 → 新名の対応表：

旧名	新名
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

アップグレード時の対応： ツール名を参照している MCP クライアントの設定、システムプロンプト、スクリプト、自動化処理で、mindwtr. を mindwtr_ に検索・置換してください。ほかに変更は必要ありません。

---

ツール

• mindwtr_list_tasks
  • 入力：{ status?, projectId?, includeDeleted?, limit?, offset?, search?, dueDateFrom?, dueDateTo?, isFocusedToday?, view?, sortBy?, sortOrder? }
  • view は GTD の利用可能状況（available、deferred、blocked）で絞り込みます
• mindwtr_list_projects
  • 入力：{}
• mindwtr_get_project
  • 入力：{ id, includeDeleted? }
• mindwtr_list_view_sections — ビューのセクション ID、タイトル、順序。view は省略可能で、someday、waiting、focus のいずれかを指定します（SQLite/Cloud）
• 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 （--write が必要）
  • 入力：{ title? | quickAdd?, status?, projectId?, sectionId?, viewSectionIds?, areaId?, dueDate?, startTime?, cancelledAt?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, reminderPolicy?, repeatReminderMinutes?, dueReminderLeadMinutes?, attachments? }
• mindwtr_update_task （--write が必要）
  • 入力：{ id, title?, status?, projectId?, sectionId?, viewSectionIds?, areaId?, dueDate?, startTime?, cancelledAt?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, reminderPolicy?, repeatReminderMinutes?, dueReminderLeadMinutes?, order?, boardOrder?, focusOrder?, attachments? }
  • reminderPolicy は開始／期限のリマインダーに対して inherit、send、skip を受け付けます。ライブラリのデフォルト設定に従うには inherit を指定します。null は受け付けません。既存のタスクは、明示的に変更するまで従来のリマインダー設定を保持します。
  • recurrence は、繰り返し設定オブジェクトまたは RFC 5545 RRULE 文字列を受け付けます。解除するには null を指定します。
  • attachments に指定できるのはリンク添付のみです（{ id?, title?, uri }、例：obsidian://、file://、https://）。指定したリストがリンクの完全なセットになります。指定しなかったリンクは削除されますが、ファイル添付には影響しません。null を指定するとすべてのリンクが削除されます。
  • cancelledAt はタイムゾーン付きの ISO タイムスタンプです。設定すると、完了としてカウントされたり次の繰り返しが生成されたりすることなく、タスクをキャンセル済み（archived）として終了します。アクティブなステータスに変更するか、完了すると、キャンセル状態は解除されます。キャンセルを使用する前に、同期中のすべてのクライアントを更新してください。古い書き込みクライアントはこのマーカーを破棄する可能性があります。
• mindwtr_complete_task （--write が必要）
  • 入力：{ id }
• mindwtr_delete_task （--write が必要）
  • 入力：{ id }
• mindwtr_restore_task （--write が必要）
  • 入力：{ id }
• mindwtr_add_project （--write が必要）
  • 入力：{ title, color?, status?, areaId?, isSequential?, isFocused?, viewSectionIds?, dueDate?, startDate?, cancelledAt?, reviewAt?, supportNotes?, attachments? }
• mindwtr_update_project （--write が必要）
  • 入力：{ id, title?, color?, status?, areaId?, isSequential?, isFocused?, viewSectionIds?, dueDate?, startDate?, cancelledAt?, reviewAt?, supportNotes?, attachments? }
  • attachments には mindwtr_update_task と同じルールが適用されます。リンク添付のみを指定でき、リストはリンクの完全なセットになります。null を指定するとすべてのリンクが削除されます。
• mindwtr_delete_project （--write が必要）
  • 入力：{ id }
• mindwtr_add_section （--write が必要）
  • 入力：{ projectId, title, description?, order?, isCollapsed? }
• mindwtr_update_section （--write が必要）
  • 入力：{ id, title?, description?, order?, isCollapsed? }
• mindwtr_delete_section （--write が必要）
  • 入力：{ id }
• mindwtr_add_area （--write が必要）
  • 入力：{ name, color?, icon? }
• mindwtr_update_area （--write が必要）
  • 入力：{ id, name?, color?, icon? }
• mindwtr_delete_area （--write が必要）
  • 入力：{ id }
• mindwtr_add_person （--write が必要）
  • 入力：{ name, note?, referenceLink? }
• mindwtr_update_person （--write が必要）
  • 入力：{ id, name?, note?, referenceLink? }
• mindwtr_rename_person （--write が必要）
  • 入力：{ id, name, updateTasks? }
• mindwtr_delete_person （--write が必要）
  • 入力：{ id } すべてのツールは、タスク、プロジェクト、セクション、エリア、人物、コレクションの結果ペイロードを含む JSON テキストペイロードを返します。

---

テスト

簡易スモークテスト（CLI）

1. サーバーを起動します（読み取り専用）：

bun run mindwtr:mcp -- --db "~/.local/share/mindwtr/mindwtr.db"

2. MCP クライアントで接続し、次を実行します：

• mindwtr_list_tasks（limit 5）

書き込みをテストする場合は、--write を付けて再起動します：

bun run mindwtr:mcp -- --db "~/.local/share/mindwtr/mindwtr.db" --write

次に、以下をテストします：

• mindwtr_add_task（quickAdd: "Test task @home /due:tomorrow"）
• mindwtr_complete_task（返されたタスク ID を使用）
• mindwtr_update_task（例：status または dueDate を設定）
• mindwtr_delete_task（返されたタスク ID を使用）
• mindwtr_get_task（返されたタスク ID を使用）
• mindwtr_restore_task（削除後、タスクを復元）
• mindwtr_list_projects
• mindwtr_get_project（返されたプロジェクト ID を使用）
• mindwtr_list_areas
• mindwtr_list_people
• mindwtr_add_project
• mindwtr_update_project
• mindwtr_delete_project
• mindwtr_add_area
• mindwtr_update_area
• mindwtr_delete_area
• mindwtr_add_person
• mindwtr_update_person
• mindwtr_rename_person
• mindwtr_get_person（返された人物 ID を使用）
• mindwtr_delete_person
• mindwtr_list_tasks（dueDateFrom、dueDateTo、sortBy、sortOrder を指定）

一覧にタスクが返され、追加と完了が機能する場合、サーバーは正常に動作しています。

Stdio JSON-RPC E2E（トランスポートの検証）

任意の MCP クライアントまたは簡単なスクリプトを使って、次を送信します：

• initialize
• notifications/initialized
• tools/list
• tools/call（例：mindwtr_list_projects または mindwtr_list_tasks）

これらが成功すれば、stdio トランスポートはエンドツーエンドで機能しています。

Claude Code の動作確認

1. サーバーを追加します：

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

2. Claude Code を再起動し、/mcp を実行して、mindwtr が接続されていることを確認します。
3. モデルに次のツールを呼び出すよう依頼します：
   • mindwtr_list_tasks（limit 5）
   • mindwtr_add_task（quickAdd: "Test MCP @home /due:tomorrow"）
   • mindwtr_complete_task（返された ID を使用）

---

安全性と同時実行性

以下の SQLite に関する説明は、直接データベースモードに適用されます。ローカル API モードではデスクトップアプリのネイティブハンドラーを使用し、クラウドモードではセルフホスト可能なサーバーを使用します。

• サーバーは SQLite WAL モードを使用します。デスクトップアプリの起動中も、読み取り専用ツールを実行できます。
• 書き込みツールは、SQLite の書き込みロックがある場合は速やかに失敗し、その後 Mindwtr の書き込み操作全体を再試行します。再試行のたびに変更を適用する前に最新のデータを読み込むため、遅延した MCP の書き込みがロック前の古いスナップショットを使い続けることはありません。
• 書き込みはデフォルトで無効です。編集を有効にするには --write を使用します。
• 書き込み操作は共有の @mindwtr/core ストアを経由し、ビジネスルールを適用します（Bun と Node の両方）。
• SQL は、パフォーマンスが重要な読み取り中心の処理（一覧表示／検索）に限って使用します。
• デスクトップアプリが書き込みを行っている間は、別のコンテナー／サーバーのデプロイを同じローカルストレージに接続したり、データを同期したりしないでください。ローカル SQLite の調整経路を通らない独立した書き込み元が生じるため、サポートされていません。

---

注記

• この MCP サーバーは、デスクトップアプリが使用する SQLite データベースを対象としており、変更は @mindwtr/core 経由で行われます。
• アプリのバージョン間でのスキーマ変更に注意してください（必要に応じてクエリを更新してください）。

ビューのセクション割り当て

SQLite モードと Cloud モードでは、mindwtr_list_view_sections（必要に応じて {"view":"someday"} を指定）を呼び出して、セクション ID とタイトルを確認します。結果は {"viewSections":[{"view":"someday","id":"books","title":"Books","order":0}]} です。 これらはビューの見出しであり、mindwtr_list_sections が返すプロジェクトのセクションとは別です。ビューの見出しは Mindwtr アプリで作成または名前を変更します。

タスクとプロジェクトの作成／更新ツールでは、たとえば viewSectionIds を指定できます。 {"someday":"books","waiting":"people"} のように指定します。見出しを割り当てても、エンティティのステータスは変わりません。更新時はマップ全体が置き換えられるため、維持したい他のビューの割り当ても含めてください。割り当てを維持するにはフィールドを省略します。すべての割り当てをクリアするには {} を渡すか、更新時に null を渡します。特定のビューだけをクリアするには、他の割り当てのみを含むマップを送信します。値には空でないセクション ID 文字列を指定する必要があります。新しいアプリとの互換性のため、未知のビュー名も引き続きサポートされます。

カタログは読み取り専用モードで利用できます。割り当ての書き込みには --write が必要です。Cloud モードは既存のデータエンドポイントを使用し、Mindwtr Cloud 1.3.7 で動作します。Desktop Local API モードでは、既知の ID によるタスクの割り当てに対応していますが、ビューのセクションカタログやプロジェクトの割り当ては公開されません。サポートされていない入力は拒否されます。