Things MCP Server

Things MCP Server

このModel Context Protocol（MCP）サーバーを使うと、Claude DesktopからThings appのタスク管理データを操作できます。Claudeにタスクの作成、プロジェクトの分析、優先順位の管理などを依頼できます。

このサーバーは、Things.pyライブラリとThings URL Schemeを活用し、さらに次のような信頼性を高める機能を備えています。

• 指数バックオフと再試行メカニズムによる堅牢なエラー処理
• 障害の連鎖を防ぐサーキットブレーカーパターン
• 失敗した操作を記録するデッドレターキュー
• パフォーマンス向上のためのインテリジェントなキャッシュ
• 構造化されたJSON出力による包括的なログ記録
• URLスキームで失敗する操作に対応するAppleScriptブリッジ
• Things appへの過剰な負荷を防ぐレート制限
• 信頼性を高めるための広範なテストスイート

Things MCPを選ぶ理由

このMCPサーバーにより、タスク管理でAIの力を活用できます。

• 自然言語によるタスク作成：自然な言葉で詳細を伝えて、Claudeにタスクを作成してもらえます
• スマートなタスク分析：プロジェクトや生産性のパターンに関する分析結果を得られます
• GTDと生産性向上のワークフロー：生産性向上システムの導入をClaudeに支援してもらえます
• シームレスな統合：既存のThings 3データと直接連携します

機能

• Thingsの主要なリスト（Inbox、Today、Upcomingなど）にアクセス
• プロジェクトとエリアの管理
• タグの操作
• 高度な検索機能
• 最近のアイテムの追跡
• チェックリストを含むアイテムの詳細情報
• ネストされたデータに対応（エリア内のプロジェクト、プロジェクト内のTo-do）

インストール方法

Things MCPサーバーをインストールして使用する方法はいくつかあります。

方法1：PyPIからインストール（推奨）

前提条件

• Python 3.12+
• Claude Desktop
• Things 3（Settings -> Generalで「Enable Things URLs」をオンにする必要があります）
• Things Authentication Token（URLスキームの操作に必要）

インストール

pip install things-mcp

または、uvを使用します（推奨）。

uv pip install things-mcp

実行

インストール後、サーバーを直接実行できます。

things-mcp

方法2：手動インストール

前提条件

• Python 3.12+
• Claude Desktop
• Things 3（Settings -> Generalで「Enable Things URLs」をオンにする必要があります）

ステップ1：uvをインストール

まだインストールしていない場合は、uvをインストールします。

curl -LsSf https://astral.sh/uv/install.sh | sh

その後、ターミナルを再起動してください。

ステップ2：このリポジトリをクローン

git clone https://github.com/hald/things-mcp
cd things-mcp

ステップ3：Python環境と依存関係をセットアップ

uv venv
uv pip install -r pyproject.toml

ステップ4：Things認証トークンを設定

設定ツールを実行して、Things認証トークンを設定します。

python configure_token.py

このツールの案内に従ってThings認証トークンを設定してください。このトークンは、MCPサーバーがThings appと連携するために必要です。

ステップ5：Claude Desktopを設定

Claude Desktopの設定ファイルを編集します。

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

設定ファイルのmcpServersキーにThingsサーバーを追加します（インストールしたフォルダーへのパスに更新してください）。

{
    "mcpServers": {
        "things": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",
                "run",
                "things_server.py"
            ]
        }
    }
}

ステップ6：認証トークンを設定

Things URL schemeには認証トークンが必要です。トークンはThings → Settings → Generalで確認できます。

方法1：設定スクリプトで設定

python configure_token.py

方法2：環境変数で設定

export THINGS_AUTH_TOKEN="your-token-here"

方法3：設定ファイルを手動で作成

mkdir -p ~/.things-mcp
echo '{"things_auth_token": "your-token-here"}' > ~/.things-mcp/config.json

ステップ7：Claude Desktopを再起動

変更を適用するため、Claude Desktopアプリを再起動します。

Claude Desktopでの使用例

• 「今日のTo-doリストには何がありますか？」
• 「来週のビーチ旅行の荷造り用にTo-doを作成して、荷造りチェックリストを含めてください。」
• 「アイゼンハワー・マトリクスを使って、現在のTo-doを評価してください。」
• 「Thingsを使ったGTD方式の週次レビューを手伝ってください。」

ヒント

• Things の使い方や、エリア、プロジェクト、タグなどの整理方法を説明するカスタム指示を設定して、Claude にプロジェクトを作成します。新しいタスクを作成する際に含めてほしい情報を Claude に伝えましょう（たとえば、タスクの説明に関連情報を含めるよう指示すると便利です）。
• Claude がカレンダーにアクセスできるように、別の MCP サーバーを追加してみましょう。これにより、特定のタスクのためにカレンダーの時間を確保したり、今後のカレンダーイベント（例：会議の準備）から ToDo を作成したりするよう Claude に依頼できます。

利用可能なツール

リストビュー

• get-inbox - インボックスの ToDo を取得
• get-today - 今日が期限の ToDo を取得
• get-upcoming - 今後の ToDo を取得
• get-anytime - Anytime リストの ToDo を取得
• get-someday - Someday リストの ToDo を取得
• get-logbook - 完了した ToDo を取得
• get-trash - ゴミ箱に移動した ToDo を取得

基本操作

• get-todos - ToDo を取得。プロジェクトで絞り込むこともできます
• get-projects - すべてのプロジェクトを取得
• get-areas - すべてのエリアを取得

タグ操作

• get-tags - すべてのタグを取得
• get-tagged-items - 特定のタグが付いたアイテムを取得

検索操作

• search-todos - タイトル／メモを対象に簡易検索
• search-advanced - 複数のフィルターを使った詳細検索

時間ベースの操作

• get-recent - 最近作成されたアイテムを取得

変更操作

• add-todo - すべてのパラメーターを指定して新しい ToDo を作成
• add-project - タグと ToDo を含む新しいプロジェクトを作成
• update-todo - 既存の ToDo を更新
• update-project - 既存のプロジェクトを更新
• delete-todo - ToDo を削除（ゴミ箱に移動）
• delete-project - プロジェクトを削除（ゴミ箱に移動）
• show-item - Things 内の特定のアイテムまたはリストを表示
• search-items - Things 内のアイテムを検索

ツールのパラメーター

get-todos

• project_uuid （任意）- プロジェクトで ToDo を絞り込む
• include_items （任意、デフォルト：true）- チェックリスト項目を含める

get-projects / get-areas / get-tags

• include_items （任意、デフォルト：false）- 含まれるアイテムを含める

search-advanced

• status - ステータスで絞り込む（未完了／完了／キャンセル済み）
• start_date - 開始日で絞り込む（YYYY-MM-DD）
• deadline - 期限で絞り込む（YYYY-MM-DD）
• tag - タグで絞り込む
• area - エリアの UUID で絞り込む
• type - アイテムの種類で絞り込む（to-do/project/heading）

get-recent

• period - 期間（例：'3d'、'1w'、'2m'、'1y'）

add-todo

• title - ToDo のタイトル
• notes （任意）- ToDo のメモ
• when （任意）- ToDo をスケジュールするタイミング（today、tomorrow、evening、anytime、someday、または YYYY-MM-DD）
• deadline （任意）- ToDo の期限（YYYY-MM-DD）
• tags （任意）- ToDo に付けるタグ
• list_title または list_id （任意）- 追加先のプロジェクト／エリアのタイトルまたは ID
• heading （任意）- 追加先の見出し
• checklist_items （任意）- 追加するチェックリスト項目

update-todo

• id - 更新する ToDo の ID
• title （任意）- 新しいタイトル
• notes （任意）- 新しいメモ
• when （任意）- 新しいスケジュール
• deadline （任意）- 新しい期限
• tags （任意）- 新しいタグ
• completed （任意）- 完了としてマーク
• canceled （任意）- キャンセル済みとしてマーク

add-project

• title - プロジェクトのタイトル
• notes （任意）- プロジェクトのメモ
• when （任意）- プロジェクトをスケジュールするタイミング
• deadline （任意）- プロジェクトの期限
• tags （任意）- プロジェクトに付けるタグ
• area_title または area_id （任意）- 追加先のエリアのタイトルまたは ID
• todos （任意）- プロジェクト内に作成する初期 ToDo

update-project

• id - 更新するプロジェクトの ID
• title （任意）- 新しいタイトル
• notes （任意）- 新しいメモ
• when （任意）- 新しいスケジュール
• deadline （任意）- 新しい期限
• tags （任意）- 新しいタグ
• completed （任意）- 完了としてマーク
• canceled （任意）- キャンセル済みとしてマーク

delete-todo

• id - 削除する ToDo の ID（ゴミ箱に移動）

delete-project

• id - 削除するプロジェクトの ID（ゴミ箱に移動します）

show-item

• id - 表示するアイテムの ID、または次のいずれか：inbox、today、upcoming、anytime、someday、logbook
• query（任意） - 絞り込みに使用する任意のクエリ
• filter_tags（任意） - 絞り込みに使用する任意のタグ

重要な制限事項

タグ

• タグを ToDo やプロジェクトに適用するには、Things にそのタグが存在している必要があります
• 使用しようとしたタグが存在しない場合、MCP サーバーが自動的に作成します
• タグの作成に失敗しても、ToDo／プロジェクトはタグなしで作成されます

認証トークン

• すべての URL スキーム操作（作成、更新、削除）で必要です
• トークンがない場合、操作のたびに Things から認証を求められます

認証トークンの設定

Things MCP サーバーが Things アプリと連携するには、認証トークンが必要です。このトークンは、URL スキームコマンドの認証に使用されます。

Things の認証トークンの取得方法

1. Mac で Things アプリを開きます
2. Things → Preferences（⌘,）に移動します
3. General タブを選択します
4. 「Enable Things URLs」にチェックが入っていることを確認します
5. 環境設定ウィンドウに表示されている認証トークンを確認します

トークンの設定

付属の設定ツールを実行して、トークンを設定します。

python configure_token.py

この対話型スクリプトでトークンの入力を求められ、ローカル設定に安全に保存されます。

開発

このプロジェクトでは、依存関係とビルド設定の管理に pyproject.toml を使用しています。Model Context Protocol を使用して構築されており、Claude がツールやデータに安全にアクセスできます。

実装オプション

このプロジェクトでは、異なる 2 つの実装方式を提供しています。

1. 標準 MCP サーバー（things_server.py） - 基本的な MCP サーバーパターンを使用する、元の実装です。

2. FastMCP サーバー（things_fast_server.py） - デコレーターによるツール登録を使用し、よりすっきりとした保守しやすいコードを実現する、FastMCP パターンを用いた最新の実装です。

開発ワークフロー

開発環境のセットアップ

# Clone the repository
git clone https://github.com/hald/things-mcp
cd things-mcp

# Set up a virtual environment with development dependencies
uv venv
uv pip install -e ".[dev]"  # Install in development mode with extra dependencies

開発中の変更のテスト

MCP 開発サーバーを使用して変更をテストします。

# Test the FastMCP implementation
mcp dev things_fast_server.py

# Or test the traditional implementation
mcp dev things_server.py

PyPI 用パッケージのビルド

python -m build

PyPI への公開

twine upload dist/*

Python 3.12 以降が必要です。

信頼性機能

エラー処理と復旧

• 再試行ロジック：一時的な障害に対し、指数バックオフを使用して自動的に再試行します
• サーキットブレーカー：障害の繰り返しによってシステムに過剰な負荷がかかるのを防ぎます
• デッドレターキュー：失敗した操作を、後での再試行や分析に備えて保存します
• AppleScript フォールバック：URL スキーム操作が失敗した場合、AppleScript による直接操作に切り替えます

パフォーマンスの最適化

• スマートキャッシュ：頻繁にアクセスされるデータを、適切な TTL でキャッシュします
• レート制限：Things アプリに過剰な数のリクエストが送られるのを防ぎます
• キャッシュの無効化：データの変更時にキャッシュを自動的に消去します

監視とデバッグ

• 構造化ログ：分析しやすい JSON 形式のログを記録します
• 操作の追跡：各操作について、所要時間とステータスを記録します
• キャッシュ統計：get-cache-stats ツールでキャッシュのパフォーマンスを監視します
• ログの場所：
  • メインログ：~/.things-mcp/logs/things_mcp.log
  • 構造化ログ：~/.things-mcp/logs/things_mcp_structured.json
  • エラーログ：~/.things-mcp/logs/things_mcp_errors.log

トラブルシューティング

サーバーには、次の項目に対するエラー処理が含まれています。

• 無効な UUID
• 必須パラメーターの不足
• Things データベースへのアクセスエラー
• データ形式エラー
• 認証トークンの問題
• ネットワークのタイムアウト
• AppleScript の実行失敗

よくある問題

1. トークンがない、または無効：python configure_token.py を実行してトークンを設定してください
2. Things が起動していない：サーバーは Things を自動的に起動しようとします
3. URL スキームが有効になっていない：Things → Preferences → General で「Enable Things URLs」が有効になっていることを確認してください
4. 操作が失敗する：サーキットブレーカーの状態とデッドレターキューを確認してください
5. パフォーマンスの問題：get-cache-stats ツールでキャッシュ統計を監視してください

ログの確認

すべてのエラーは記録され、説明的なメッセージとともに返されます。MCP のログを確認するには：

# Follow main logs in real-time
tail -f ~/.things-mcp/logs/things_mcp.log

# Check error logs
tail -f ~/.things-mcp/logs/things_mcp_errors.log

# View structured logs for analysis
cat ~/.things-mcp/logs/things_mcp_structured.json | jq

# Claude Desktop MCP logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

高度なデバッグ

1. デッドレターキューを確認：失敗した操作は things_dlq.json に保存されます
2. サーキットブレーカーを監視：ログ内の「Circuit breaker」メッセージを探してください
3. キャッシュのパフォーマンス：get-cache-stats ツールを使用してヒット率を確認してください
4. デバッグログを有効化：logging_config.py でコンソールレベルを DEBUG に設定してください