Things MCP サーバー

このモデルコンテキストプロトコル（MCP）サーバーを使用すると、Claude Desktop を使ってThings アプリ内のタスク管理データを操作できます。Claude にタスクの作成、プロジェクトの分析、優先順位の管理などを依頼できます。

このサーバーは、 Things.pyライブラリとThings URL スキームを活用します。

なぜ Things MCP なのか?

この MCP サーバーは、タスク管理に AI のパワーを活用します。

• 自然言語タスク作成: クロードに、すべての詳細を自然言語で記述したタスクの作成を依頼します。

• スマートタスク分析: プロジェクトと生産性パターンに関する洞察を得る

• GTDと生産性ワークフロー：クロードが生産性システムの導入をお手伝いします

• シームレスな統合:既存のThings 3データと直接連携

Related MCP server: Things MCP

特徴

• すべての主要な Things リスト (受信トレイ、今日、今後の予定など) へのアクセス

• プロジェクトおよびエリア管理

• タグ操作

• 高度な検索機能

• 最近のアイテムの追跡

• チェックリストを含む詳細なアイテム情報

• ネストされたデータのサポート（エリア内のプロジェクト、プロジェクト内の ToDo）

インストールオプション

Things MCP サーバーをインストールして使用するには、複数の方法があります。

オプション 1: PyPI からインストールする (推奨)

前提条件

• Python 3.12以上

• クロードデスクトップ

• Things 3（設定 -> 一般で「Things URL を有効にする」をオンにする必要があります）

インストール

pip install things-mcp

または uv を使用する (推奨):

uv pip install things-mcp

ランニング

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

things-mcp

オプション2: 手動インストール

前提条件

• Python 3.12以上

• クロードデスクトップ

• Things 3（設定 -> 一般で「Things URL を有効にする」をオンにする必要があります）

ステップ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

ここでは、MCP サーバーが Things アプリと対話するために必要な Things 認証トークンを構成する手順について説明します。

ステップ5: Claudeデスクトップを構成する

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: Claude Desktopを再起動する

変更を適用するには、Claude デスクトップ アプリを再起動します。

Claude Desktop の使用例

• 「今日のToDoリストには何がある？」

• 「来週のビーチでの休暇に備えて荷造りの ToDo リストを作成し、荷造りチェックリストも含めます。」

• 「アイゼンハワー マトリックスを使用して現在の ToDo を評価します。」

• 「Things を使用して GTD スタイルの週次レビューを実施するのを手伝ってください。」

ヒント

• Claude で、Things の使用方法や、エリア、プロジェクト、タグなどの整理方法を説明するカスタム手順を含むプロジェクトを作成します。新しいタスクを作成するときに含めてほしい情報を Claude に伝えます (たとえば、タスクの説明に関連する詳細を含めるように依頼すると役立つ場合があります)。

• Claude にカレンダーへのアクセスを許可する別の MCP サーバーを追加してみてください。これにより、Claude にカレンダーの特定のタスクの時間をブロックしたり、今後のカレンダーイベント（例: 会議の準備）から ToDo を作成したりといった操作を依頼できるようになります。

利用可能なツール

リストビュー

• get-inbox - 受信トレイからToDoを取得する

• get-today - 今日期限のToDoを取得する

• get-upcoming - 今後のToDoを取得する

• get-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 - 最近作成されたアイテムを取得する

ツールパラメータ

やるべきことを取得する

• project_uuid (オプション) - プロジェクトごとにToDoをフィルタリングします

• include_items (オプション、デフォルト: true) - チェックリスト項目を含める

プロジェクトを取得 / エリアを取得 / タグを取得

• include_items (オプション、デフォルト: false) - 含まれるアイテムを含める

詳細検索

• status - ステータス（未完了/完了/キャンセル）でフィルタリング

• start_date - 開始日（YYYY-MM-DD）でフィルタリング

• deadline - 締め切り（YYYY-MM-DD）でフィルタリング

• tag - タグでフィルタリング

• area - エリアUUIDでフィルタリング

• type - アイテムの種類（ToDo/プロジェクト/見出し）でフィルタリング

最新を取得

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

追加-ToDo

• title - ToDoのタイトル

• notes （オプション） - ToDoのメモ

• when (オプション) - ToDo をいつスケジュールするか (今日、明日、夕方、いつでも、いつか、または YYYY-MM-DD)

• deadline （オプション） - ToDo の締め切り（YYYY-MM-DD）

• tags (オプション) - ToDoに適用するタグ

• list_titleまたはlist_id (オプション) - 追加するプロジェクト/エリアのタイトルまたはID

• heading （オプション） - 下に追加する見出し

• checklist_items (オプション) - 追加するチェックリスト項目

更新-todo

• id - 更新するToDoのID

• title （オプション） - 新しいタイトル

• notes （オプション） - 新しいメモ

• when （オプション） - 新しいスケジュール

• deadline （オプション） - 新しい締め切り

• tags （オプション） - 新しいタグ

• completed （オプション） - 完了としてマークする

• canceled （オプション） - キャンセル済みとしてマーク

プロジェクトを追加

• title - プロジェクトのタイトル

• notes （オプション） - プロジェクトのメモ

• when （オプション） - プロジェクトをいつスケジュールするか

• deadline （オプション） - プロジェクトの締め切り

• tags (オプション) - プロジェクトに適用するタグ

• area_titleまたはarea_id (オプション) - 追加するエリアのタイトルまたはID

• todos (オプション) - プロジェクトで作成する最初のtodos

プロジェクトの更新

• id - 更新するプロジェクトのID

• title （オプション） - 新しいタイトル

• notes （オプション） - 新しいメモ

• when （オプション） - 新しいスケジュール

• deadline （オプション） - 新しい締め切り

• tags （オプション） - 新しいタグ

• completed （オプション） - 完了としてマークする

• canceled （オプション） - キャンセル済みとしてマーク

表示項目

• id - 表示するアイテムの ID、または次のいずれか: inbox、today、coming、anyway、someday、logbook

• query （オプション） - フィルタリングするオプションのクエリ

• filter_tags (オプション) - フィルタリングするオプションのタグ

認証トークンの設定

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

Things認証トークンを取得する方法

1. MacでThingsアプリを開く

2. Things → 設定 (⌘,) に移動します。

3. 一般タブを選択します

4. 「Things URLを有効にする」がチェックされていることを確認してください

5. 設定ウィンドウに表示される認証トークンを探します

トークンの設定

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

python configure_token.py

この対話型スクリプトはトークンの入力を要求し、それをローカル構成に安全に保存します。

発達

このプロジェクトは、依存関係とビルド構成の管理にpyproject.toml使用しています。モデルコンテキストプロトコルを使用して構築されているため、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 以上が必要です。

トラブルシューティング

サーバーには次のエラー処理が含まれています:

• 無効なUUID

• 必要なパラメータが不足しています

• データベースアクセスエラー

• データフォーマットエラー

• 認証トークンの問題

よくある問題

1. トークンが見つからないか無効です: python configure_token.pyを実行してトークンを設定してください

2. Things アプリが実行されていない: MCP サーバーを使用するときは、Things 3 が開いていることを確認してください

3. URLスキームが有効になっていません: 「Things」→「設定」→「一般」で「Things URLを有効にする」が有効になっていることを確認してください

ログの確認

すべてのエラーはログに記録され、説明メッセージとともに返されます。Claude Desktop の MCP ログを確認するには、ターミナルで次のコマンドを実行してください。

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log