mcp-task-manager

AnthropicのModel Context Protocolを通じてClaude Desktopにプラグインするローカルタスクマネージャーです。UIもバックエンドサービスも不要で、PythonプロセスとSQLiteファイルだけで動作します。Claudeと会話するだけでタスクを管理できます。

「認証バグを修正する優先度の高いタスクを作成して。期限は金曜日、タグはbackendで。」 → タスクが作成されます。 「今日何に集中すべき？」 → 期限切れ、緊急、優先度の高いタスクを返します。 「タスク3を完了にして、概要を表示して。」 → 完了処理と統計を表示します。

スタック: Python 3.11+ · FastMCP · SQLite · Pydantic v2 ステータス: ローカルで動作確認済み、9つのツールを実装済み

このプロジェクトの目的

MCPのサーバーライフサイクル、ツール登録、stdioトランスポート、そしてClaudeが自然言語リクエストからどのようにツールを選択するかをエンドツーエンドで学習するために構築されました。小規模ながら完成された例であり、職場での実用的な内部ツールへと拡張できるような構成になっています。

仕組み

MCPサーバーはローカルのサブプロセスとして実行されます。Claude DesktopはJSON-RPCを使用してstdio経由でサーバーと通信します。メッセージを入力すると、Claudeは以下の処理を行います：

1. リクエストに適合する登録済みツールを選択する

2. 自然言語からパラメータを埋める

3. ツールを呼び出し、構造化データ（Pydanticモデル）を受け取る

4. 結果を平易な英語で要約してあなたに返す

Claude Desktop  ──── JSON-RPC (stdio) ────  server.py  (FastMCP)
                                                │
                                         TaskRepository
                                                │
                                           tasks.db  (SQLite)

ツール

優先度: low · medium · high · urgent ステータス: pending · in_progress · completed · cancelled

プロジェクト構成

mcp-task-manager/
├── server.py           # FastMCP entry point, tool registration, lifespan
├── core/
│   ├── models.py       # Pydantic models + enums (Task, TaskCreate, TaskUpdate, TaskSummary)
│   └── repository.py   # SQLite DAO — CRUD, search, summary
├── tools/
│   └── __init__.py     # 9 MCP tool functions (thin layer over repository)
├── pyproject.toml
└── .env.example

3つの層で構成され、それぞれが1つの責務を担います：

• tools/ — MCP向けのインターフェース。各関数には、Claudeが呼び出しのタイミングや方法を理解するためのdocstringが含まれています。

• core/repository.py — SQLiteへのアクセス。status、priority、due_date にインデックスを貼った生のSQLを実行します。

• core/models.py — バリデーション、シリアライズ、列挙型（Enum）。

セットアップ

要件: Python 3.11+、Claude Desktop。

git clone https://github.com/soltyDude/mcp-task-manager.git
cd mcp-task-manager

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .
cp .env.example .env

Claude Desktopへの接続

Claude Desktopの設定ファイルを開きます：

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

• Windows — %APPDATA%\Claude\claude_desktop_config.json

サーバーを追加します：

{
  "mcpServers": {
    "mcp-task-manager": {
      "command": "/absolute/path/to/mcp-task-manager/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-task-manager/server.py"]
    }
  }
}

Claude Desktopを再起動します。🔌アイコンの下にツールが表示されます。

設定

.env は2つの変数をサポートしています：

DATABASE_PATH=tasks.db       # where SQLite stores data
SERVER_NAME=mcp-task-manager # name shown in Claude Desktop

使用例

You:    Add a task: refactor the auth filter, high priority, due tomorrow, tags: backend, security

Claude: Created task #1 — "Refactor the auth filter" (high, due 2025-04-19, tags: backend, security)

You:    What's my plan for today?

Claude: 📅 Day plan for 2025-04-18
        🔥 FOCUS (urgent + high priority)
          [1] [HIGH] Refactor the auth filter  #backend #security
        📊 Total: 1 | In progress: 0 | Overdue: 0

You:    Mark it in progress and show a summary

Claude: Task #1 updated — status: in_progress.
        📊 Total: 1 | Pending: 0 | In progress: 1 | Completed: 0 | Overdue: 0

設計上の注意点

レビュー担当者向けに、いくつかの設計上の選択について説明します：

• ライフサイクルスコープのリポジトリ。 TaskRepository はFastMCPの lifespan コンテキストマネージャー内で一度だけ構築され、ctx.request_context.lifespan_context を介して注入されます。ツールはステートレスに保たれ、接続詳細はツールコードに漏れません。

• マジック文字列ではなく列挙型を使用。 Priority と TaskStatus は str 列挙型であり、入力時にPydanticで検証され、SQLiteには文字列として保存され、その間は常に型付けされます。

• TEXTカラムにJSONとしてタグを保存。 ローカルツールとしては結合テーブルが不要なため、実用的な選択です。検索にはシリアライズされたJSONに対する LIKE を使用します。将来的にPostgresへ移行する場合は、text[] 型や正規のタグテーブルに変更する予定です。

• ホットパスのインデックス化。 すべてのフィルタリングでヒットする status、priority、due_date の3つのカラムにインデックスを貼っています。

• plan_day での重複排除。 緊急タスクと高優先度タスクのクエリは期限切れリストと重複する可能性があるため、最終的なフォーカスリストは seen セットを使用して構築されます。

制限事項 / 今後のステップ

• まだテストがありません。リポジトリ層に対してインメモリSQLiteフィクスチャを使用した pytest を計画中です。

• 定期的なタスク機能はありません。

• 検索は LIKE ベースです。データセットが大きくなった場合は、SQLite FTS5へのアップグレードを検討します。

• 設計上、シングルユーザー・シングルマシンを想定しています。マルチユーザー対応には、SQLiteをPostgresに置き換え、ユーザーカラムを追加する必要があります。

ライセンス

MIT