Todo List MCP Server

Простой, дружелюбный к новичкам Model Context Protocol (MCP) сервер, написанный на Python. Он позволяет любому MCP-совместимому ИИ-клиенту (например, Claude Desktop) управлять списком дел на вашем компьютере через пять инструментов: добавить, просмотреть, получить по ID, завершить и удалить.

Создан с использованием официального MCP Python SDK (mcp[cli]) и его высокоуровневого интерфейса FastMCP. Данные хранятся локально в обычном JSON-файле — база данных не требуется.

1. Что делает этот проект

Этот MCP-сервер предоставляет 5 инструментов любому подключённому ИИ-клиенту:

Все данные хранятся в todos.json, который создаётся автоматически при первом добавлении задачи.

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

Откроется браузерный интерфейс, где вы можете вызывать каждый инструмент вручную и видеть JSON-ответы.

Вариант B — Установка в Claude Desktop:

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

Это регистрирует сервер, чтобы Claude Desktop запускал его автоматически.

Вариант C — Запуск напрямую:

python server.py

5. Тестирование / Примеры запросов (в Claude Desktop)

После подключения в Claude Desktop попробуйте:

• "Добавь задачу: Купить продукты, с описанием Молоко, яйца и хлеб"

• "Покажи все мои задачи"

• "Получи задачу с ID 1"

• "Отметь задачу 1 как выполненную"

• "Удали задачу 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-сервером, клиентом и инструментами/ресурсами/промптами

• Как использовать интерфейс FastMCP из официального Python SDK для быстрого создания инструментов из обычных Python-функций и аннотаций типов

• Как хранить и управлять данными локально с помощью JSON-файла

• Как подключить и протестировать собственный MCP-сервер внутри Claude Desktop

• Как упаковать, документировать и опубликовать небольшой Python-проект на GitHub

• Основы публикации MCP-сервера на маркетплейсе, таком как Smithery

Лицензия

MIT — можно свободно использовать, изменять и распространять.

Автор

Haseeba Yasin

Если этот проект оказался полезным, не стесняйтесь поставить ⭐ репозиторию.