Things3 MCP Server

Things3 MCP サーバー

macOS 上の Things3 と包括的に連携する MCP（Model Context Protocol）サーバーです。このサーバーを使うと、AI アシスタントやその他の MCP クライアントが、25 種類の専用ツールを通じて Things3 を操作できます。インテリジェントなエラー修正やタグの自動作成機能を備え、タスク管理に必要な機能をすべて提供します。

特長

• Things3 との完全な連携：Things3 のあらゆる機能をカバーする25種類のツール
• TODO 管理：タスクの作成、読み取り、更新、削除、完了、未完了への変更
• プロジェクトとエリアの管理：エリア整理や削除を含む、プロジェクトのライフサイクル全体をサポート
• タグシステム：階層タグのサポート、作成、削除、一括タグ操作
• 一括操作：複数の項目を一度に効率よく移動または更新
• タグの自動作成：TODO／プロジェクト操作で参照されたタグを自動的に作成
• エラー修正：よくある問題（日付の競合、タイトルの欠落）を自動的に修正
• ログブック検索：日付範囲で絞り込んで完了済み項目を検索
• パフォーマンスの最適化：接続プーリングと AppleScript の最適化

必要条件

• macOS（Things3 は macOS 専用です）
• Node.js >= 16.0.0
• Things3 アプリがインストールされていること
• AppleScript のアクセスが「システム設定」で有効になっていること

インストール

クイックスタート（推奨）

インストールせずにサーバーを使用できます。

{
  "mcpServers": {
    "things3": {
      "command": "npx",
      "args": ["things3-mcp@latest"],
      "env": {
        "THINGS3_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

npm からインストール

npm install -g things3-mcp

続いて、MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "things3": {
      "command": "things3-mcp",
      "env": {
        "THINGS3_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

ソースからインストール

# Clone the repository
git clone https://github.com/urbanogardun/things3-mcp.git
cd things3-mcp

# Install dependencies
npm install

# Build the project
npm run build

設定

環境変数

更新操作（変更、完了、削除）を行うには、Things3 の認証トークンを設定する必要があります。

export THINGS3_AUTH_TOKEN="your_auth_token_here"

認証トークンを確認するには：

1. Things3 を開きます
2. 「設定」→「一般」に移動します
3. 「Enable Things URLs」をクリックします
4. 「Manage」をクリックします
5. 認証トークンの値をコピーします

.env ファイルを作成することもできます（.env.example を参照）。

Claude Desktop の場合

1. Claude Desktop の設定を開きます。

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

2. 次のいずれかの方法で Things3 MCP サーバーを追加します。

   方法 1：npx を使用（最も簡単、インストール不要）

   {
     "mcpServers": {
       "things3": {
         "command": "npx",
         "args": ["things3-mcp@latest"],
         "env": {
           "THINGS3_AUTH_TOKEN": "your_auth_token_here"
         }
       }
     }
   }
   

   方法 2：npm でグローバルインストール

   {
     "mcpServers": {
       "things3": {
         "command": "things3-mcp",
         "env": {
           "THINGS3_AUTH_TOKEN": "your_auth_token_here"
         }
     }
   }
   

   方法 3：ローカルインストール

   {
     "mcpServers": {
       "things3": {
         "command": "node",
         "args": ["/absolute/path/to/things3-mcp/dist/index.js"]
       }
     }
   }
   

3. Claude Desktop を再起動します。

その他の MCP クライアントの場合

上記のいずれかの方法を使用し、設定をお使いの MCP クライアントの形式に合わせてください。

利用可能なツール

TODO ツール（7）

todos_list

柔軟なフィルターオプションを使って TODO を一覧表示します。

パラメーター：

• filter："inbox" | "today" | "upcoming" | "anytime" | "someday" | "logbook"（任意）
• searchText：タイトルとメモを検索します（任意）

例：

{
  "filter": "today",
  "searchText": "meeting"
}

todos_get

特定の TODO の詳細情報を取得します。

パラメーター：

• id：TODO の一意の識別子（必須）

todos_create

すべてのプロパティに対応した新しい TODO を作成します（存在しないタグは自動的に作成されます）。

パラメーター：

• title：タスクのタイトル（必須）
• notes：追加のメモ（任意）
• whenDate：スケジュール用の ISO 8601 日付文字列（任意）
• deadline：期限用の ISO 8601 日付文字列（任意）
• tags：タグ名の配列（任意）
• checklistItems：チェックリスト項目のタイトルの配列（任意）*
• projectId：プロジェクトに割り当てます（任意）
• areaId：エリアに割り当てます（任意）
• heading：追加先となるプロジェクト内の見出しのタイトル（任意）

例：

{
  "title": "Review Q4 Report",
  "notes": "Focus on revenue metrics",
  "whenDate": "2024-12-15T09:00:00Z",
  "deadline": "2024-12-20T17:00:00Z",
  "tags": ["work", "urgent"],
  "checklistItems": ["Review revenue", "Check expenses", "Update forecast"],
  "projectId": "project-id-here"
}

* チェックリストに関する注意： checklistItems が指定されている場合、TODO は AppleScript ではなく Things3 の URL スキームを使用して作成されます。この方法には、次の制限があります。

• Things3 が一時的に前面に表示されることがあります
• 作成された TODO の ID を直接取得できないため、サーバーはタイトルで検索します
• 同じタイトルの TODO が複数ある場合、誤った TODO が返される可能性があります
• Things3 の設定で URL スキームのサポートを有効にする必要があります（Settings → General → Enable Things URLs）

todos_update

既存の TODO のプロパティを更新します（存在しないタグは自動的に作成されます）。

パラメーター：

• id：TODO 識別子（必須）
• todos_create のすべてのパラメーター（任意）

todos_complete

1 つ以上の TODO を完了済みにします。

パラメーター：

• ids：単一の ID または ID の配列（必須）

todos_uncomplete

1 つ以上の TODO を未完了にします。

パラメーター：

• ids：単一の ID または ID の配列（必須）

todos_delete

1 つ以上の TODO を完全に削除します。

パラメーター：

• ids：単一の ID または ID の配列（必須）

プロジェクトツール（6）

projects_list

任意の条件で絞り込んでプロジェクトを一覧表示します。

パラメーター：

• areaId：エリアで絞り込みます（任意）
• includeCompleted：完了済みのプロジェクトを含めます（任意、デフォルト：false）

projects_get

プロジェクトの詳細情報を取得します。

パラメーター：

• id：プロジェクト識別子（必須）

projects_create

新しいプロジェクトを作成します（存在しないタグは自動的に作成されます）。

パラメーター：

• name：プロジェクト名（必須）
• notes：プロジェクトの説明（任意）
• areaId：エリアに割り当てます（任意）
• whenDate：開始日（任意）
• deadline：期限（任意）
• tags：タグ名の配列（任意）
• headings：セクション見出しの配列（任意）

projects_update

プロジェクトのプロパティを更新します（存在しないタグは自動的に作成されます）。

パラメーター：

• id：プロジェクト識別子（必須）
• headings を除く projects_create のすべてのパラメーター（任意）

projects_complete

プロジェクトを完了済みにします。

パラメーター：

• id：プロジェクト識別子（必須）

projects_delete

Things3 からプロジェクトを完全に削除します。

パラメーター：

• ids：単一のプロジェクト ID またはプロジェクト ID の配列（必須）

エリアツール（3）

areas_list

すべてのエリアを一覧表示します。

パラメーター：

• includeHidden：非表示のエリアを含めます（任意、デフォルト：false）

areas_create

新しいエリアを作成します。

パラメーター：

• name：エリア名（必須）

areas_delete

Things3 からエリアを完全に削除します。

パラメーター：

• ids：単一のエリア ID またはエリア ID の配列（必須）

タグツール（5）

tags_list

階層情報を含めてすべてのタグを一覧表示します。

戻り値： ネストされたタグの parentTagId を含むタグの配列

tags_create

新しいタグを作成します。

パラメーター：

• name：タグ名（必須）
• parentTagId：ネストする場合の親タグ（任意）

tags_add

項目にタグを追加します（存在しないタグは自動的に作成されます）。

パラメーター：

• itemIds：単一の ID または TODO／プロジェクト ID の配列（必須）
• tags：追加するタグ名の配列（必須）

tags_remove

項目からタグを削除します。

パラメーター：

• itemIds：単一の ID または TODO／プロジェクト ID の配列（必須）
• tags：削除するタグ名の配列（必須）

tags_delete

Things3 からタグを完全に削除します。

パラメーター:

• names: 単一のタグ名、またはタグ名の配列（必須）

一括操作ツール（2）

bulk_move

複数の TODO をプロジェクトまたはエリアに移動します。

パラメーター:

• todoIds: TODO ID の配列（必須）
• projectId: 移動先のプロジェクト（任意）
• areaId: 移動先のエリア（任意）

bulk_updateDates

複数の TODO の日付を更新します。

パラメーター:

• todoIds: TODO ID の配列（必須）
• whenDate: 新しい予定日。日付をクリアする場合は null（任意）
• deadline: 新しい締切日。日付をクリアする場合は null（任意）

ログブックツール（1）

logbook_search

ログブック内の完了済みアイテムを検索します。

パラメーター:

• searchText: タイトルとメモを検索します（任意）
• fromDate: 期間の開始日（任意）
• toDate: 期間の終了日（任意）
• limit: 結果の最大数（任意、デフォルト: 50）

システムツール（1）

system_launch

Things3 が起動して使用できる状態であることを確認します。

エラーの自動修正

サーバーは一般的な問題を自動的に修正します。

• 日付の競合: 締切日が予定日より前の場合、予定日と締切日を入れ替えます
• タイトルの欠落: メモからタイトルを生成するか、「無題」を使用します
• 無効な参照: プロジェクトまたはエリアが存在しない場合、アイテムを Inbox に移動します
• タグ名: Things3 がサポートしていない特殊文字を削除します

使用例

Claude Desktop での使用

Human: Create a new project for the website redesign with tasks for planning, design, and implementation

Claude: I'll create a website redesign project with those tasks for you.

[Creates project and tasks using the Things3 MCP tools]

ツールを直接使用する

TODO を作成する:

{
  "tool": "todos_create",
  "parameters": {
    "title": "Prepare presentation",
    "notes": "Include Q4 metrics and projections",
    "whenDate": "2024-12-10T14:00:00Z",
    "tags": ["work", "presentation"]
  }
}

今日のタスクを一覧表示する:

{
  "tool": "todos_list",
  "parameters": {
    "filter": "today"
  }
}

開発

開発環境のセットアップ

# Install dependencies
npm install

# Run in development mode with watch
npm run dev

# Run tests
npm test

# Run integration tests (requires Things3)
npm run test:integration

# Lint code
npm run lint

# Type check
npm run type-check

プロジェクト構成

things3-mcp/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # MCP server implementation
│   ├── config.ts         # Configuration management
│   ├── tools/            # Tool implementations
│   │   ├── todos.ts      # TODO operations
│   │   ├── projects.ts   # Project operations
│   │   ├── areas.ts      # Area operations
│   │   ├── tags.ts       # Tag operations
│   │   ├── bulk.ts       # Bulk operations
│   │   ├── logbook.ts    # Logbook search
│   │   └── system.ts     # System utilities
│   ├── templates/        # AppleScript templates
│   ├── utils/            # Utility functions
│   │   ├── applescript.ts     # AppleScript bridge
│   │   ├── cache-manager.ts   # Caching system
│   │   ├── error-correction.ts # Error correction
│   │   └── date-handler.ts    # Date formatting
│   └── types/            # TypeScript definitions
├── tests/
│   ├── unit/            # Unit tests
│   └── integration/     # Integration tests
└── dist/                # Compiled JavaScript

トラブルシューティング

Things3 が応答しない

1. Things3 がインストールされ、起動していることを確認します
2. システム設定 > プライバシーとセキュリティ > プライバシー > オートメーションで AppleScript のアクセス許可を確認します
3. Things3 を操作するためのアクセス許可を、ターミナルまたは IDE に付与します

アクセス許可エラー

• macOS では、オートメーションのアクセス許可を付与する必要がある場合があります
• 次のコマンドを実行して AppleScript のアクセスをテストします:

  osascript -e 'tell application "Things3" to return name of first to do'
  

MCP 接続の問題

1. 設定内のパスが絶対パスであることを確認します
2. サーバーが正常にビルドされることを確認します: npm run build
3. MCP クライアントのログでエラーメッセージを確認します
4. サーバーを直接実行してみます: node dist/index.js

日付形式の問題

• 日付は ISO 8601 形式で指定する必要があります（例: "2024-12-25T10:00:00Z"）
• サーバーはタイムゾーンの変換を自動的に処理します
• 日付が正しく表示されない場合は、システムの日付形式設定を確認します

パフォーマンスの問題

• 大規模な操作では、個別の操作ではなく一括操作ツールを使用します
• タグ操作では不足しているタグが自動的に作成されるため、初回の操作が遅くなる場合があります

既知の制限事項

1. チェックリスト項目:
   • Things3 の AppleScript API はチェックリストの操作をサポートしていません
   • チェックリスト付きの TODO を作成する際は、回避策として URL スキームを使用します
   • これにより、Things3 が一時的に前面に表示される場合があります
   • 作成後に既存のチェックリスト項目を変更することはできません
2. 削除したアイテムの復元: API 経由で削除したアイテムを復元することはできません
3. リマインダーの詳細: AppleScript で取得できるリマインダー情報は限られています
4. タグの階層: タグの親子関係は読み取り専用です（ただし、タグの作成と削除は可能です）
5. URL スキームの制限:
   • URL スキームを使用する場合（チェックリスト用）、新しく作成された TODO の ID を直接取得することはできません
   • サーバーは作成された TODO を見つけるために検索を行いますが、同じタイトルの TODO が複数ある場合は失敗する可能性があります

コントリビューション

コントリビューションを歓迎します。プルリクエストを送信する前に、Conventional Commits の形式に従い、すべてのテストが成功することを確認してください。

謝辞

• Model Context Protocol SDK を使用して構築されています
• Cultured Code の Things3 と連携します
• MCP コミュニティおよびさまざまな自動化ツールから着想を得ています