chenjiahui-offical/mcp-todo-server

MCP Todo Server

A production-ready MCP (Model Context Protocol) server for task management with email reminders, hosted on Cloudflare Workers.

✨ Features

• 📝 Full CRUD Operations - Create, read, update, and delete tasks
• ⏰ Smart Reminders - Customizable email reminders before deadlines
• 🌍 Multi-Timezone Support - Server uses UTC, users see their local time
• 👥 Multi-User - Isolated data per user (identified by email)
• 📧 Email Notifications - Beautiful HTML email templates
• 🔄 Auto-Expiry - Automatic task expiration detection
• 🚀 Edge Computing - Deployed on Cloudflare Workers (global CDN)
• 💾 SQLite Database - Cloudflare D1 for reliable storage
• 🔐 Secure - Environment-based secrets management

🏗️ Architecture

AI Client (Claude/Kiro/etc)
    ↓ SSE (Server-Sent Events)
MCP Server (Cloudflare Workers)
    ↓
Database (Cloudflare D1 - SQLite)
    ↓
Cron Jobs (Every 5 minutes)
    ↓
Email Service (Resend/SendGrid)

🚀 Quick Start

Prerequisites

• Node.js 18+
• Cloudflare account (free tier works)
• Email service account (Resend or SendGrid recommended)

1. Clone and Install

git clone https://github.com/chenjiahui-offical/mcp-todo-server.git
cd mcp-todo-server
npm install

2. Deploy

# Install Wrangler CLI
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Create D1 database
wrangler d1 create mcp-todo-db

# Update wrangler.toml with the database_id from above

# Initialize database
wrangler d1 execute mcp-todo-db --remote --file=./schema.sql

# Set secrets
echo "your_resend_api_key" | wrangler secret put SMTP_PASS
echo "noreply@yourdomain.com" | wrangler secret put SMTP_FROM_EMAIL

# Deploy
npm run deploy

3. Configure Your AI Client

See for detailed configuration instructions for:

• Claude Desktop
• Kiro IDE
• Cline (VS Code)
• Continue (VS Code)
• Custom clients

Quick Example (VS Code):

{
  "mcpServers": {
    "todo": {
      "url": "https://your-worker.workers.dev/sse",
      "transport": "sse",
      "env": {
        "USER_EMAIL": "your-email@example.com",
        "USER_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

📖 Documentation

• - 5-minute deployment guide
• - Detailed deployment instructions
• - Client configuration for various AI tools
• - Architecture and technical details

🛠️ MCP Tools

💬 Usage Examples

Add a Task

Add a task:
- Title: Complete project report
- Description: Include data analysis and conclusions
- Deadline: tomorrow at 3 PM
- Remind me 1 hour before
- Priority: high
- Tags: work, important

List Tasks

Show all my pending tasks

Update Task

Change the deadline of "Complete project report" to next Friday at 5 PM

Mark Complete

Mark "Complete project report" as completed

🗄️ Database Schema

Users Table

CREATE TABLE users (
    email TEXT PRIMARY KEY,
    timezone TEXT NOT NULL DEFAULT 'UTC',
    created_at INTEGER NOT NULL
);

Todos Table

CREATE TABLE todos (
    id TEXT PRIMARY KEY,
    user_email TEXT NOT NULL,
    title TEXT NOT NULL,
    description TEXT,
    deadline_utc INTEGER NOT NULL,
    remind_before_minutes INTEGER NOT NULL DEFAULT 60,
    priority TEXT DEFAULT 'medium',
    tags TEXT,
    is_completed INTEGER DEFAULT 0,
    is_expired INTEGER DEFAULT 0,
    reminder_sent INTEGER DEFAULT 0,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL,
    FOREIGN KEY (user_email) REFERENCES users(email)
);

⚙️ Configuration

Environment Variables

Set via wrangler secret put:

• SMTP_PASS - Email service API key (Resend/SendGrid)
• SMTP_FROM_EMAIL - Sender email address

wrangler.toml

name = "mcp-todo-server"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[d1_databases]]
binding = "DB"
database_name = "mcp-todo-db"
database_id = "your-database-id"

[triggers]
crons = ["*/5 * * * *"]  # Every 5 minutes

[vars]
SMTP_HOST = "api.resend.com"
SMTP_PORT = "443"
SMTP_FROM_NAME = "MCP Todo Reminder"

🔧 Development

Local Development

npm run dev

Run Tests

./scripts/test-api.sh http://localhost:8787

View Logs

wrangler tail

Query Database

wrangler d1 execute mcp-todo-db --remote --command "SELECT * FROM todos"

📊 Project Structure

mcp-todo-server/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── db.ts             # Database operations
│   ├── email.ts          # Email sending
│   ├── cron.ts           # Scheduled tasks
│   ├── timezone.ts       # Timezone utilities
│   └── types.ts          # TypeScript types
├── scripts/
│   ├── setup.sh          # Setup automation
│   └── test-api.sh       # API testing
├── schema.sql            # Database schema
├── wrangler.toml         # Cloudflare config
├── package.json          # Dependencies
└── README.md             # This file

🔐 Security

• Email-based user identification
• Data isolation per user
• HTTPS encryption (Cloudflare default)
• Environment-based secrets
• No authentication required (email serves as identifier)

Production Recommendations:

• Add API token authentication
• Implement rate limiting
• Add audit logging
• Use CORS whitelist

🌍 Timezone Handling

• Server: All times stored in UTC
• User: Times displayed in user's configured timezone
• Conversion: Automatic bidirectional conversion
• Format: IANA timezone database (e.g., 'Asia/Shanghai')

📧 Email Service Setup

Using Resend (Recommended)

1. Sign up at https://resend.com
2. Verify your domain
3. Get API key
4. Update src/email.ts (already configured for Resend)

Using SendGrid

1. Sign up at https://sendgrid.com
2. Get API key
3. Update src/email.ts to use SendGrid API

See for detailed instructions.

🐛 Troubleshooting

Database Connection Failed

# Check database ID in wrangler.toml
wrangler d1 list

# Verify tables exist
wrangler d1 execute mcp-todo-db --remote --command "SELECT name FROM sqlite_master WHERE type='table'"

Email Not Sending

# Check logs
wrangler tail

# Verify email service configuration
# Check src/email.ts implementation

Timezone Issues

• Use IANA format: 'Asia/Shanghai' ✅
• Don't use: 'GMT+8' ❌
• Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

📈 Performance

• Cloudflare Workers: Global edge network
• D1 Database: Optimized SQLite with indexes
• Cron Jobs: Efficient 5-minute intervals
• Email: Async sending with retry logic

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see file for details

🙏 Acknowledgments

• Model Context Protocol
• Cloudflare Workers
• Resend

📞 Support

• Issues: GitHub Issues
• Documentation: See folder
• Health Check: https://your-worker.workers.dev/health

🗺️ Roadmap

• API token authentication
• Task categories and filters
• Recurring tasks
• Task attachments
• Task sharing
• Statistics and reports
• Mobile app integration
• Webhook support

Made with ❤️ for the MCP community

If you find this project useful, please ⭐ star it on GitHub!