Todo List MCP Server

Python で書かれた、シンプルで初心者にも優しい Model Context Protocol (MCP) サーバーです。 MCP 互換の AI クライアント（Claude Desktop など）が、追加・表示・ID による取得・完了・削除の 5 つのツールを通じて、コンピュータ上の To-Do リストを管理できるようにします。

公式の MCP Python SDK（mcp[cli]）と、その高レベル FastMCP インターフェースを使用して構築されています。 データはプレーンな JSON ファイルにローカル保存されるため、データベースは不要です。

1. このプロジェクトの概要

この MCP サーバーは、接続された AI クライアントに 5 つのツールを公開します。

すべてのデータは todos.json に保存され、最初に To-Do を追加したときに自動的に作成されます。

Related MCP server: Task MCP Server

2. プロジェクト構成

todo-mcp-server/
├── server.py          # Main MCP server — defines the 5 tools
├── storage.py          # Handles reading/writing todos.json
├── todos.json           # Auto-created data file (not committed to git)
├── requirements.txt     # Python dependencies     
├── .gitignore            # Files Git should ignore
└── README.md             

3. セットアップ

前提条件

• Python 3.10 以降

• pip（Python に同梱）

手順

# 1. Clone or download this project, then move into it
cd todo-mcp-server

# 2. Create a virtual environment
python -m venv venv

# 3. Activate it
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

4. サーバーの実行

オプション A — MCP Inspector（テスト推奨）:

mcp dev server.py

これにより、ブラウザベースの UI が開き、各ツールを手動で呼び出して JSON レスポンスを確認できます。

オプション B — Claude Desktop にインストール:

mcp install server.py --name "Todo List MCP Server"

これによりサーバーが登録され、Claude Desktop が自動的に起動するようになります。

オプション C — 直接実行:

python server.py

5. テスト / プロンプト例（Claude Desktop 内）

Claude Desktop に接続したら、次を試してください：

• 「To-Do を追加: 牛乳、卵、パンという説明付きで「食料品を買う」」

• 「すべての To-Do を表示して」

• 「ID 1 の To-Do を取得して」

• 「To-Do 1 を完了にして」

• 「To-Do 2 を削除して」

6. アーキテクチャ

 MCP Client (Claude Desktop)
          │  (stdio / JSON-RPC)
          ▼
     server.py  (FastMCP tools)
          │
          ▼
     storage.py (reads/writes JSON)
          │
          ▼
     todos.json  (local data file)

クライアントは JSON ファイルに直接触れることはありません。ツールを呼び出すだけで、データの保存方法はサーバーが決定します。この分離は MCP の設計思想の核となるもので、クライアントはツールが内部的にどのように動作するかを知る必要はなく、何をするかだけを知っていればよいのです。

7. 学んだこと

このプロジェクトを通して学んだこと：

• Model Context Protocol (MCP) とは何か、そして LLM のツールアクセスをどのように標準化するか

• MCP サーバー、クライアント、ツール/リソース/プロンプトの違い

• 公式 Python SDK の FastMCP インターフェースを使用して、プレーンな Python 関数と型ヒントからツールをすばやく構築する方法

• JSON ファイルを使用してデータをローカルに保存・管理する方法

• Claude Desktop 内でカスタム MCP サーバーを接続してテストする方法

• 小さな Python プロジェクトを GitHub でパッケージ化、ドキュメント化、公開する方法

• Smithery のようなマーケットプレイスに MCP サーバーを公開する基本

ライセンス

MIT — 自由に使用、変更、共有できます。

著者

Haseeba Yasin

このプロジェクトが役に立ったと思ったら、お気軽にリポジトリに ⭐ を付けてください。