Todo MCP Server

🚀 Todo MCP Server

A simple to-do application built using the Model Context Protocol (MCP) for testing and demonstrating MCP interactions.

🚀 Quick Start

This repository contains a minimal to-do application implemented as an MCP server. It allows you to perform the following operations:

• List all to-do items
• View a specific to-do item
• Add a new to-do item
• Delete a to-do item
• Clear all to-do items
• Create structured tasks with metadata

This project serves as a testbed for interacting with the Model Context Protocol server and understanding how to build and expose functionality through the MCP protocol. For more information about the Model Context Protocol, please visit modelcontextprotocol.io.

✨ Features

• Comprehensive Operations: Supports listing, viewing, adding, deleting, and clearing to - do items, as well as creating structured tasks.
• MCP Integration: Demonstrates how to interact with the MCP server and register with MCP - supported applications.
• Multiple Deployment Options: Can be installed via traditional methods, added to MCP server lists, or run using Docker.

📦 Installation

Prerequisites

• Python 3.10 or higher
• uv (Python package installation tool)

Installation Steps

1. Clone the repository:

git clone https://github.com/idsulik/todo-mcp-server.git
cd todo-mcp-server

2. Install dependencies using uv:

uv pip install -e .

Add to MCP Server List

To add this server to your MCP server list, use the following command:

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

This registers the server with the Claude desktop application or other MCP - supported applications.

If you need to test the server using the MCP inspector, you can use:

mcp dev server.py

This will start the server with an MCP inspector interface for easy testing and debugging.

Manual Addition to MCP Configuration

If you prefer to manually add the server to your MCP configuration, you can add the following JSON to the Claude desktop configuration file (usually located at ~/.claude-desktop/claude_desktop_config.json or C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "todo": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp",
        "server.py"
      ]
    }
  }
}

Please replace server.py with the actual file path.

Docker

To run the server using Docker, run the following commands:

docker pull ghcr.io/idsulik/todo-mcp-server:latest
docker run -it ghcr.io/idsulik/todo-mcp-server:latest

💻 Usage Examples

API Usage

The server exposes interfaces through the following MCP resources and tools:

Resources

1. List all to - do items:

GET todo://list

2. View a specific to - do item:

GET todo://view/{item_idx}

where item_idx is the index of the to - do item you want to view.

Prompts

1. Create a structured task:

create_task(task_name: str, priority: str = "medium", due_date: str = "")

This prompt helps format to - do tasks with priority and due date. Parameters:

• task_name: The name/description of the task
• priority: Task priority (low, medium, high)
• due_date: The due date of the task (optional)

Tools

1. Add a new to - do item:

add_todo(value: str)

2. Delete a to - do item:

remove_todo(item_idx: int)

3. Clear all to - do items:

clear_todo()

📄 License

No license information provided in the original document.

🤝 Contribution

Pull requests are welcome for this project!