claude-todo-emulator 0.3.1
This is an MCP server that emulates Claude Code's task management system, providing persistent todo functionality for AI coding assistants in IDEs like Cursor, Windsurf, and others.
Requires Python: >=3.11
Keywords: mcp, claude, todo, task-management, ai-assistant

# Claude Todo MCP Server

[![PyPI Version](https://img.shields.io/pypi/v/claude-todo-emulator.svg)](https://pypi.org/project/claude-todo-emulator/)
[![PyPI Downloads](https://static.pepy.tech/badge/claude-todo-emulator)](https://pepy.tech/projects/claude-todo-emulator)

**Add persistent task management to any AI coding assistant in Cursor, Windsurf, and other IDEs.**

This MCP server replicates Claude Code's todo system, giving your AI assistant the ability to:

- Track complex multi-step tasks across sessions
- Break down large features into manageable pieces
- Remember progress when you switch between projects
- Enforce single in-progress task focus

## Quick Start

**No installation required!** Just add this to your MCP configuration:

### Cursor IDE

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "task-manager": {
      "command": "uvx",
      "args": ["claude-todo-emulator"]
    }
  }
}
```

### Codex CLI

Create `config.toml` at your project root:

```toml
[mcp_servers.task-manager]
command = "uvx"
args = ["claude-todo-emulator"]
```

### Other IDEs

Add the JSON configuration above to your MCP settings file.

**Restart your IDE** and try: _"Create a todo list for adding user authentication"_

The system automatically downloads the package and sets up everything on first use!

## What You Get

Once configured, your AI assistant will automatically:

**Create todos for complex tasks:**

```
You: "Add dark mode support with user preferences"
AI: "I'll create a todo list for this multi-step feature:
- ✅ Add theme context and state management
- 🔄 Create dark mode CSS variables and styles
- ⏳ Build settings UI for theme switching
- ⏳ Add persistence to localStorage
- ⏳ Update existing components for theme support"
```

**Track progress visually:**

```
You: "What's the status on the authentication system?"
AI: "Current authentication tasks:
- ✅ Set up JWT middleware
- ✅ Create login/signup endpoints
- 🔄 Building user profile management (in progress)
- ⏳ Add password reset flow
- ⏳ Implement role-based permissions"
```

**Maintain focus:**

```
You: "Let's also add email notifications"
AI: "I'll add that to the todo list, but let me finish the current user profile task first to maintain focus."
```

### API Reference

**TodoRead**

- Parameters: None
- Returns: `{todos: Todo[]}`

**TodoWrite**

- Parameters: `{todos: Todo[]}`
- Returns: `{success: boolean, count: number}`

**Todo Schema**

```typescript
{
  id: string;
  content: string;
  status: "pending" | "in_progress" | "completed";
  priority: "high" | "medium" | "low";
  created_at: string;
  updated_at: string;
  metadata?: object;
}
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Related Projects

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP](https://gofastmcp.com/)
- [Claude Code](https://www.anthropic.com/claude-code)