mcp-tdo is a Model Context Protocol (MCP) server that allows AI models to access and manage your todo notes and tasks through the tdo CLI tool.

✨ Features

• Retrieve todo note contents for today, tomorrow, or any date offset
• Search across all notes for specific content
• List all pending todos across all your notes
• Get count of pending todos across all your notes
• Create new todo notes
• Mark specific todos as complete
• Add new todo items to existing note files
• Fully compatible with the MCP specification

⚡ Setup

⚙️ Requirements

• Python 3.10+
• tdo CLI tool installed and accessible in your PATH
• uv for local development

💻 Installation

From PyPI (Recommended)

Install mcp-tdo from PyPI using pip or uv:

# Using pip
pip install mcp-tdo

# Using uv (recommended)
uv add mcp-tdo

# Using pipx (for CLI tools)
pipx install mcp-tdo

From Source

For development or to get the latest changes:

git clone https://github.com/2kabhishek/mcp-tdo
cd mcp-tdo
uv sync --dev

🚀 Usage

Running the Server

If installed from PyPI:

mcp-tdo

Or specify a custom path to the tdo executable:

mcp-tdo --tdo-path /path/to/tdo.sh

If running from source:

uv run mcp-tdo

MCP Server Configuration

To use this MCP server, add it to your MCP client configuration:

Option 1: Using direct command (PyPI install)

{
  "mcpServers": {
    "mcp-tdo": {
      "command": "mcp-tdo"
    }
  }
}

If your tdo executable is not in PATH:

{
  "mcpServers": {
    "mcp-tdo": {
      "command": "mcp-tdo",
      "args": ["--tdo-path", "/path/to/your/tdo"]
    }
  }
}

Option 2: Using uv for development

{
  "mcpServers": {
    "mcp-tdo": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-tdo", "mcp-tdo"]
    }
  }
}

Option 3: Using python directly

{
  "mcpServers": {
    "mcp-tdo": {
      "command": "python",
      "args": ["-m", "mcp_tdo"]
    }
  }
}

🧩 Available Tools

get_todo_contents

Shows contents of todo notes for today or a specific date offset.

Parameters:

• offset: (optional) Offset like "1" for tomorrow, "-1" for yesterday, etc.

search_notes

Searches for notes matching a query term.

Parameters:

• query: Search query term

get_pending_todos

Shows all pending todos (unchecked checkboxes) from all your notes.

No parameters required.

get_todo_count

Shows the count of pending todos across all your notes.

No parameters required.

create_note

Creates a new todo note at the specified path.

Parameters:

• note_path: Path/name for the new note (e.g., 'tech/vim' or 'ideas')

mark_todo_done

Marks a specific todo item as done.

Parameters:

• file_path: Path to the file containing the todo
• todo_text: Text of the todo item to mark as done

add_todo

Adds a new todo item to a specified file.

Parameters:

• file_path: Path to the file to add the todo to
• todo_text: Text of the todo item to add

🔧 Development

This project uses uv for dependency management and Ruff for linting and formatting.

Setup

# Clone the repository
git clone https://github.com/2kabhishek/mcp-tdo
cd mcp-tdo

# Install dependencies (including dev dependencies)
uv sync --dev

Common Development Commands

# Run tests
uv run pytest tests/ -v

# Run linter
uv run ruff check src/ tests/

# Format code
uv run ruff format src/ tests/

# Fix linting issues automatically
uv run ruff check --fix src/ tests/

# Run the MCP server locally
uv run mcp-tdo

# Install the package in development mode
uv sync

Project Structure

├── src/mcp_tdo/          # Main package
│   ├── models.py         # Data models
│   ├── tdo_client.py     # TDO CLI integration
│   └── server.py         # MCP server implementation
├── tests/                # Test suite
├── pyproject.toml        # Project configuration
└── uv.lock              # Dependency lockfile

🏗️ What's Next

✅ To-Do

You tell me!

🧑‍💻 Behind The Code

🌈 Inspiration

mcp-tdo was inspired by the need to give AI assistants access to personal task management tools, allowing for more productive interactions with AI models.

💡 Challenges/Learnings

• Implementing proper error handling and command execution
• Working with the MCP protocol specification
• Managing file path and content operations safely

🧰 Tooling

• dots2k — Dev Environment
• nvim2k — Personalized Editor
• sway2k — Desktop Environment
• qute2k — Personalized Browser

🔍 More Info

• shelly — Command line template
• tiny-web — Web app template

---