Amazing Marvin MCP Server

🌐 Hosted on Smithery - Install-free access to Amazing Marvin through Claude and other MCP clients

A high-quality Model Context Protocol (MCP) server that connects AI assistants to Amazing Marvin, the powerful task management and productivity system. Built with FastMCP and deployed on Smithery for hosted, zero-installation access.

✨ What's New in v2.0 (Smithery)

Complete migration to Smithery for hosted deployment:

• 🌐 Hosted Infrastructure: No local installation, Python, or dependencies required
• 🔐 Secure Configuration: API tokens managed through Smithery's session config
• 📊 Usage Monitoring: Track server usage and performance
• 🚀 Auto-deployment: Push to GitHub → Automatic deployment
• 🔄 Auto-scaling: Handle multiple concurrent users
• 💪 Same Power: All 10 tools with identical functionality

Technical improvements:

• FastMCP framework with @smithery.server() decorator
• Pydantic V2 validation with session config schemas
• Context-aware API authentication
• Dual response formats (Markdown/JSON)
• Enhanced error handling with actionable guidance

Quick Start

For Users

1. Get your Amazing Marvin API token

   • Visit https://app.amazingmarvin.com/pre?api=
   • Copy your API_TOKEN

2. Connect via Smithery

   • Visit: https://smithery.ai/server/amazing-marvin-mcp
   • Click "Connect"
   • Paste your API token when prompted
   • Use in Claude Desktop or other MCP clients

3. Start using

   "Show me my tasks for today"
   "Create a task to review Q4 budget tomorrow"
   "What categories do I have?"
   

For Developers

See SMITHERY_DEPLOYMENT.md for deployment guide.

Local testing:

uv venv
uv pip install -r requirements.txt
uv run playground

Features

This MCP server provides 10 powerful tools for Amazing Marvin:

📋 Task Management

• marvin_add_task - Create tasks with full support for scheduling, labels, time estimates, and Amazing Marvin shortcuts
• marvin_get_todays_tasks - View all tasks scheduled for today or a specific date
• marvin_mark_done - Mark tasks as complete (idempotent)
• marvin_get_due_tasks - See all tasks due today or overdue with smart overdue indicators

🗂️ Organization

• marvin_get_categories - List all your projects and categories with IDs
• marvin_get_labels - View all available labels with IDs
• marvin_get_children - Browse tasks within a specific project, category, or unassigned area

⏱️ Time Tracking

• marvin_start_tracking - Start time tracking on a task
• marvin_stop_tracking - Stop the currently running timer

🎨 Response Formats

All list operations support two output formats:

• Markdown (default): Human-readable with headers, emojis, and formatting
• JSON: Structured data for programmatic processing

Usage Examples

Creating Tasks

"Create a task called 'Review Q4 budget' due tomorrow with a 2-hour time estimate"

"Add a task 'Call dentist' with 15 minute estimate and schedule it for Friday"

"Create a task 'Finish presentation slides #Work @urgent ~120 +2024-03-20'"

Amazing Marvin shortcuts in task titles:

• #ProjectName - Assign to project
• @label - Add a label
• ~60 - Time estimate (60 minutes)
• +2024-03-15 - Set due date
• ^1 - Set priority

Viewing Tasks

"Show me my tasks for today"

"What tasks are due today or overdue?"

"List all tasks in my Personal category"

"Show me tasks for March 15, 2024 in JSON format"

Managing Tasks

"Mark task task_abc123xyz as complete"

"Start tracking time on task task_abc123xyz"

"Stop the timer"

Organizing

"Show me all my categories and projects"

"What labels do I have?"

"List all unassigned tasks"

Technical Details

Architecture

Smithery Deployment:

• Python 3.12+ runtime
• FastMCP framework with @smithery.server() decorator
• Context-aware authentication via ctx.session_config
• HTTP/SSE transport (not STDIO)

Configuration:

class AmazingMarvinConfig(BaseModel):
    api_token: str = Field(
        ...,
        description="Your Amazing Marvin API token. Get it from: https://app.amazingmarvin.com/pre?api=",
        min_length=10
    )

Package Structure:

src/amazing_marvin_mcp/
├── __init__.py          # Package initialization
└── server.py            # Main server with tools

Key Features

• Pydantic V2 Validation: Robust input validation with detailed constraints
• Agent-Centric Design: Tools optimized for AI workflows, not just API wrappers
• Dual Response Formats: Markdown (human-readable) and JSON (machine-readable)
• Character Limits: Intelligent handling of large responses (25,000 char limit)
• Tool Annotations: Proper hints for read-only, destructive, and idempotent operations
• Comprehensive Docstrings: Detailed documentation with examples for every tool

Error Handling

The server provides actionable error messages:

• 401 Unauthorized: Guides to check API token configuration
• 404 Not Found: Suggests verifying IDs and item existence
• 429 Rate Limit: Advises waiting before retry
• 500 Server Error: Indicates Amazing Marvin service issues

All errors include specific next steps for resolution.

Development

Local Setup

# Clone repository
git clone https://github.com/LucaDeLeo/amazing-marvin-mcp.git
cd amazing-marvin-mcp

# Create virtual environment
uv venv

# Install dependencies
uv pip install -r requirements.txt

Testing

# Use Smithery playground (ngrok port-forwarding)
uv run playground

# Or run in development mode
uv run dev

Building Package

# Build distribution
python -m build

# Verify build
ls dist/
# Should show: amazing_marvin_mcp-2.0.0-py3-none-any.whl and .tar.gz

Deployment

See SMITHERY_DEPLOYMENT.md for complete deployment guide.

Quick deploy:

1. Push to GitHub: git push origin main
2. Go to https://smithery.ai/new
3. Connect repository
4. Click "Deploy"

API Reference

This server uses Amazing Marvin's Limited Access API:

• API Documentation: https://github.com/amazingmarvin/MarvinAPI/wiki
• Help Center: https://help.amazingmarvin.com/
• API Base URL: https://serv.amazingmarvin.com/api

Endpoints used:

GET  /api/categories       - List all categories/projects
GET  /api/labels          - List all labels
GET  /api/children        - Get items in category
GET  /api/todayItems      - Get scheduled tasks
GET  /api/dueItems        - Get due/overdue tasks
POST /api/addTask         - Create task
POST /api/markDone        - Complete task
POST /api/track           - Start/stop timer

Security Notes

• API Tokens: Stored encrypted in Smithery's session config, never in code
• HTTPS Only: All communication over TLS 1.2+
• Input Validation: Pydantic models prevent injection attacks
• Limited Access API: Additional security layer vs Full Access

Contributing

Potential future enhancements:

• Document update/delete operations (/api/doc/update, /api/doc/delete)
• Project creation tool (/api/addProject)
• Goals integration (/api/goals)
• Habit tracking (/api/habits, /api/updateHabit)
• Reminders management (/api/reminder/set)
• Time blocks viewing (/api/todayTimeBlocks)
• Tracked item status (/api/trackedItem)
• Reward points system

When adding features, follow the same patterns: Pydantic model → @mcp.tool decorator → ctx: Context parameter → shared utilities → comprehensive docstring.

Support

Server Issues:

• GitHub Issues: https://github.com/LucaDeLeo/amazing-marvin-mcp/issues

Smithery Platform:

• Email: support@smithery.ai
• Discord: https://discord.gg/Afd38S5p9A

Amazing Marvin API:

• Email: support@amazingmarvin.com

License

MIT License - See LICENSE file

Acknowledgments

• Built with FastMCP
• Deployed on Smithery
• Powered by Amazing Marvin

---

Version: 2.0.0 (Smithery Deployment) Repository: https://github.com/LucaDeLeo/amazing-marvin-mcp Smithery: https://smithery.ai/server/amazing-marvin-mcp