ml0-1337/mcp-todo-server

MCP Todo Server

A Go-based Model Context Protocol (MCP) server that enhances Claude Code's task management with full-text search, templates, and analytics while maintaining compatibility with the .claude/todos/ markdown format.

Features

• ⚡ Instant startup with background search indexing
• 🔍 Full-text search across all todos
• 📊 Analytics on task completion and productivity
• 🎯 Templates for common workflows (TDD, features, bugs)
• 🔗 Todo linking for multi-phase projects
• 🌐 HTTP transport for multi-instance support
• 📁 Auto-archive completed todos by date
• ⚡ <100ms response time for all operations

Installation

# Clone the repository
git clone https://github.com/yourusername/mcp-todo-server.git
cd mcp-todo-server

# Build the server
make build

# Start the server (HTTP mode recommended)
./build/mcp-todo-server -transport http

Quick Start

# 1. Start the server on port 8080
./build/mcp-todo-server -transport http

# 2. Add to Claude Code
claude mcp add --transport http todo http://localhost:8080/mcp

# 3. Use in Claude Code
# The server automatically creates todos in your current project directory

That's it! The server is now ready to use with Claude Code.

Usage

The server provides 9 MCP tools for comprehensive task management:

Core Tools

• todo_create - Create new todos with metadata
• todo_read - View todos with filtering options
• todo_update - Update todo content and status
• todo_search - Full-text search across all todos

Advanced Tools

• todo_archive - Archive completed todos
• todo_template - Create from predefined templates
• todo_link - Connect related todos
• todo_stats - View productivity metrics
• todo_clean - Bulk todo management

Example: Creating a Todo

Use todo_create to track "Implement user authentication" as a feature with high priority

Example: Searching Todos

Search for "authentication" in all todos to find related work

Configuration

Essential Flags

Common Configurations

# Long-running development sessions
./build/mcp-todo-server -transport http -session-timeout 0

# Memory-constrained systems
./build/mcp-todo-server -transport http -manager-timeout 30m

# Custom port
./build/mcp-todo-server -transport http -port 8081

Todo Structure

Todos are markdown files stored in .claude/todos/ with frontmatter:

---
todo_id: implement-auth-feature
started: 2025-01-27 14:30:00
status: in_progress
priority: high
type: feature
---

# Task: Implement user authentication

## Findings & Research
[Research notes and findings]

## Test List
[TDD test scenarios]

## Checklist
- [ ] Design auth flow
- [ ] Implement JWT tokens
- [ ] Add login endpoint

Completed todos are automatically archived to .claude/archive/YYYY/MM/DD/.

Development

For development guidelines and architecture details, see .

Quick Commands

make test-claude    # Run tests with clean output
make lint          # Run linters
make check         # Run all checks before committing

Documentation

• - Development guidelines
• - HTTP vs STDIO details
• - Comprehensive testing strategies
• - System design
• - Product requirements

Troubleshooting

Connection Issues

• Ensure server is running: ps aux | grep mcp-todo-server
• Check port availability: lsof -i :8080
• View logs: ./build/mcp-todo-server -transport http 2>server.log

Search Not Working

• Search works immediately but may show incomplete results during initial indexing
• Check for "indexing_status" in search responses
• Full search available after background indexing completes

License

This project is licensed under the .

You are free to use this software for:

• Personal projects and hobby development
• Educational and research purposes
• Non-commercial open source projects

Commercial use requires a separate license. Please contact the author for commercial licensing options.