pilpat-fastmcp/fastmcp-task-manager

FastMCP Task Manager

A comprehensive personal task management MCP server built with FastMCP and Pydantic. Manage your tasks with priorities, categories, and persistent storage through natural language interactions with AI assistants.

Features

• 7 MCP Tools: Full CRUD operations for task management
• 8 MCP Resources: Dynamic and static resources for task data access
• Type-Safe Models: Pydantic validation for all data structures
• JSON Persistence: File-based storage with atomic operations
• Rich Filtering: Query tasks by status, priority, category with pagination
• Alice & Claude Compatible: Works with all MCP-compatible clients

Quick Start

Local Development

# Clone the repository
git clone <your-repo-url>
cd FastMCP

# Install dependencies
pip install -r requirements.txt

# Run the server (STDIO for Claude Desktop)
python task_manager/task_manager.py

# Or run with HTTP transport for web access
python task_manager/task_manager.py --transport http --port 8000

FastMCP CLI

# Run with development UI
fastmcp dev task_manager/task_manager.py

# Run in production mode
fastmcp run task_manager/task_manager.py

# Install to Claude Desktop
fastmcp install task_manager/task_manager.py

Deployment Options

1. FastMCP Cloud (Recommended)

Deploy instantly to the cloud with automatic scaling:

1. Create GitHub Repository

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin <your-github-repo>
   git push -u origin main
   

2. Deploy to FastMCP Cloud

   • Visit fastmcp.cloud
   • Sign in with GitHub
   • Create new project:
     • Name: task-manager
     • Repository: Your GitHub repo
     • Entrypoint: task_manager/task_manager.py:mcp
     • Authentication: Choose based on your needs

3. Access Your Deployed Server

   https://your-project-name.fastmcp.app/mcp
   

2. Self-Hosted HTTP Server

For custom deployments:

# Run HTTP server
fastmcp run task_manager/task_manager.py --transport http --host 0.0.0.0 --port 8000

# Access at: http://localhost:8000/mcp/

Task Manager API

Tools

Resources

Data Models

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    URGENT = "urgent"

class Status(str, Enum):
    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    CANCELLED = "cancelled"

class Task(BaseModel):
    id: UUID
    title: str (1-200 chars)
    description: Optional[str] (max 1000 chars)
    category: str (max 50 chars, default: "general")
    priority: Priority (default: MEDIUM)
    status: Status (default: PENDING)
    created_at: datetime
    completed_at: Optional[datetime]

Usage Examples

With Claude Desktop

Human: Add a high priority task to prepare the quarterly report
Claude: I'll create a high priority task for you to prepare the quarterly report.

With Alice MCP Client

Human: Show me all my high priority tasks
Assistant: I'll retrieve your high priority tasks for you.

With HTTP API

# Connect to deployed server
curl https://your-project.fastmcp.app/mcp/tools/list_tasks \
  -H "Content-Type: application/json" \
  -d '{"status": "pending", "priority": "high"}'

Testing

Run the included test suite:

# Run functional tests
python task_manager/test_task_manager.py

# Test with FastMCP CLI
fastmcp inspect task_manager/task_manager.py

Configuration

Local Configuration

Use task_manager.fastmcp.json for local development:

{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "task_manager/task_manager.py",
    "entrypoint": "mcp"
  },
  "environment": {
    "dependencies": ["fastmcp>=2.12.0", "pydantic>=2.11.0"]
  },
  "deployment": {
    "transport": "stdio",
    "log_level": "INFO"
  }
}

Cloud Configuration

FastMCP Cloud automatically detects your dependencies from requirements.txt and deploys with optimal settings.

Data Storage

Tasks are persisted to JSON files with automatic location detection:

• Configurable location: Use TASK_MANAGER_DIR environment variable to specify storage directory
• Cloud deployment ready: Uses /tmp/task_manager in serverless environments (FastMCP Cloud, Railway, etc.)
• Local development: Falls back to ~/.task_manager/tasks.json for desktop use
• Atomic writes: Prevents data corruption during save operations
• JSON format: Human-readable and portable across systems
• Type validation: Pydantic ensures data integrity on load/save
• Backup friendly: Simple file-based storage for easy backups

Storage Configuration

The storage directory is determined in this priority order:

1. Environment Variable: TASK_MANAGER_DIR=/path/to/storage (highest priority)
2. Cloud/Serverless: /tmp/task_manager (if /tmp is writable)
3. Local Development: ~/.task_manager (fallback for desktop use)

For FastMCP Cloud deployment, the storage is automatically configured via environment variables in the task_manager.fastmcp.json configuration file.

Contributing

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

License

MIT License - see LICENSE file for details.

Support

• Documentation: FastMCP Docs
• Community: Discord
• Issues: GitHub Issues