things3-mcp-server

utanutan/things3-mcp-server

3.2

If you are the rightful owner of things3-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Things MCP Server is a local server implementation that allows control of the Things 3 application via an HTTP REST API using AppleScript.

Things MCP Server

Things 3 を HTTP REST API で操作できるローカルサーバー（Model Control Plane）の実装です。内部的には AppleScript を用いて Things 3 を制御します。

概要

MacOSのThings3アプリケーションをAppleScript（osascript）経由で操作するHTTP REST APIサーバーです。 タスクの一覧取得、作成、完了、更新などの操作をAPIエンドポイント経由で実行できます。

Things3のエンティティ構造と関係性

Things3は以下のエンティティを持ち、階層構造を成しています。API設計ではこれらの関係性を考慮する必要があります。

主要エンティティ

  1. エリア (Area)

    • 最上位のカテゴリで、複数のプロジェクトをグループ化する
    • 例：「開発」「仕事」「個人」など

  2. リスト (List)

    • Things3の基本的な分類機能
    • 組み込みリスト：「インボックス」「今日」「明日」「いつでも」「いつか」など

  3. プロジェクト (Project)

    • タスクをグループ化するコンテナ
    • エリアに所属させることが可能
    • 自身がヘッダやメモ、ステータスを持つ

  4. タスク (To Do / Task)

    • 実際の作業単位
    • リストまたはプロジェクトに所属
    • タイトル、メモ、期日、タグなどの属性を持つ

エンティティの関係性

エリア (Area)
  |
  +-- プロジェクト (Project)
        |
        +-- タスク (Task)

リスト (List, e.g. インボックス)
  |
  +-- タスク (Task)
  • タスクはプロジェクトまたはリストのどちらかに所属します
  • プロジェクトはエリアに所属することも、独立して存在することもできます
  • タスクはプロジェクトの中に作成するか、リスト（インボックスや今日など）に直接作成することができます

API構造設計

このエンティティ構造に基づいて、以下のAPI設計を行います。

1. エリア関連

  • GET /areas - 全エリアを一覧表示
  • GET /areas/{area_name} - 指定エリアの詳細と含まれるプロジェクトを取得

2. プロジェクト関連

  • GET /projects - 全プロジェクトを一覧表示
  • GET /projects/{project_id} - 指定プロジェクトの詳細と含まれるタスクを取得
  • POST /projects - 新規プロジェクトを作成
  • PUT /projects/{project_id} - プロジェクトを更新
  • DELETE /projects/{project_id} - プロジェクトを削除

3. リスト関連

  • GET /lists - 全リストを一覧表示
  • GET /lists/{list_name}/tasks - 指定リスト内のタスクを取得

4. タスク関連

  • GET /tasks - リストに基づくタスク取得（クエリパラメータでリスト名指定）
  • GET /tasks/{task_id} - 指定タスクの詳細取得
  • POST /tasks - 新規タスク作成（リストまたはプロジェクトを指定）
  • PUT /tasks/{task_id} - タスク更新
  • DELETE /tasks/{task_id} - タスク完了または削除

5. システム関連

  • GET /health - ヘルスチェック
  • GET /version - Things3とAPIサーバーのバージョン情報取得

リクエスト/レスポンスモデル

タスクモデル
{
  "id": "string",         // Things3の内部ID
  "title": "string",      // タスクタイトル
  "notes": "string",      // メモ（オプショナル）
  "status": "string",     // ステータス（未完了、完了など）
  "when": "string",      // 期日（ISO 8601形式、オプショナル）
  "deadline": "string",  // 期限（ISO 8601形式、オプショナル）
  "tags": ["string"],    // タグリスト（オプショナル）
  "project": "string",    // 所属プロジェクトID（オプショナル）
  "area": "string"       // 所属エリア（オプショナル）
}
プロジェクトモデル
{
  "id": "string",          // Things3の内部ID
  "name": "string",        // プロジェクト名
  "notes": "string",       // メモ（オプショナル）
  "area": "string",        // 所属エリア（オプショナル）
  "status": "string",      // ステータス（活動中、完了など）
  "task_count": "integer"  // 含まれるタスク数
}
エリアモデル
{
  "id": "string",            // Things3の内部ID
  "name": "string",          // エリア名
  "project_count": "integer" // 含まれるプロジェクト数
}

API使用例

リスト一覧取得
curl -s http://localhost:8080/lists | jq
エリア一覧取得
curl -s http://localhost:8080/areas | jq
特定エリアの詳細取得
curl -s http://localhost:8080/areas/{area_id} | jq
プロジェクト一覧取得
curl -s http://localhost:8080/projects | jq
新規プロジェクト作成
curl -X POST -H "Content-Type: application/json" -d '{"name": "新しいプロジェクト", "notes": "メモを追加", "area": "開発"}' http://localhost:8080/projects
特定リストのタスク取得
curl -s "http://localhost:8080/tasks?list_name=インボックス" | jq
新規タスク作成
curl -X POST -H "Content-Type: application/json" -d '{"title": "新しいタスク", "notes": "メモを追加"}' "http://localhost:8080/tasks?list_name=インボックス"

Things3のAppleScript対応について

日本語環境での注意点

日本語環境のThings3では以下の点に注意してください：

  • 「Inbox」は「インボックス」という名前になっています
  • その他のリスト名も日本語（「今日」「明日」「いつでも」など）になっています
  • Things3のAppleScriptでは日本語のリスト名をそのまま使用します

AppleScriptの使用方法

リスト名の取得

Things3で利用可能なリスト名を確認するには、以下のAppleScriptを使用します：

tell application "Things3" to return name of lists
プロジェクト名の取得

利用可能なプロジェクト名の一覧を取得するには、次のスクリプトを使用します：

tell application "Things3"
  set projList to ""
  repeat with p in projects
    set projList to projList & name of p & ", "
  end repeat
  return projList
end tell
タスクの作成方法
インボックスにタスクを作成
tell application "Things3"
  tell list "インボックス"
    make new to do with properties {name:"タスク名", notes:"メモ内容"}
  end tell
end tell
プロジェクトにタスクを作成
tell application "Things3"
  tell project "プロジェクト名"
    make new to do with properties {name:"タスク名", notes:"メモ内容"}
  end tell
end tell
日付の設定方法

Things3における日付の設定はやや複雑ですが、以下の方法が動作します：

tell application "Things3"
  tell list "インボックス"
    set newTask to make new to do with properties {name:"タスク名"}
  end tell
  
  -- 現在日からN日後に設定する単純な方法
  set today to current date
  set dueDate to today + (3 * days) -- 3日後の例
  set due date of newTask to dueDate
end tell

前提条件

  • macOS Monterey 12.x 以降
  • Things 3 がインストール済み
  • Python 3.8 以上
  • Homebrew
  • Git

セットアップ

# クローンしてディレクトリに移動
git clone https://your-repo-url/things3-mcp-server.git
cd things3-mcp-server

# Python 仮想環境を作成してアクティベート
python3 -m venv venv
source venv/bin/activate

# 依存パッケージをインストール
pip install -r requirements.txt

サーバーの起動

source venv/bin/activate  # 仮想環境をアクティベート
uvicorn app:app --host 127.0.0.1 --port 8000

サーバーが起動したら、http://127.0.0.1:8000/docs にアクセスすると Swagger UI でAPIドキュメントを確認できます。

API エンドポイント

タスク一覧の取得

curl http://localhost:8000/tasks
# オプションでリスト名を指定
curl http://localhost:8000/tasks?list_name=Today

新規タスクの作成

curl -X POST http://localhost:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "レポート提出",
    "notes": "明日18時まで",
    "when": "2025-07-28T18:00:00"
  }'

タスクの完了（アーカイブ）

curl -X DELETE http://localhost:8000/tasks/{task_id}

タスクの更新

curl -X PUT "http://localhost:8000/tasks/{task_id}?title=修正版レポート&notes=要確認"

注意事項

  • 本サーバーを使用するには Things 3 アプリが実行中である必要があります
  • AppleScript の実行には数百msの遅延が発生するため、高スループット用途には向きません
  • セキュリティ上の理由から、本サーバーをローカルネットワーク外に公開する場合は認証機能の追加を推奨します