Task Manager MCP Server
A production-ready Task Manager server built with the Model Context Protocol (MCP), enabling AI assistants to manage tasks through a standardized interface. Built with TypeScript, Zod validation, and the official MCP SDK.
Features
- ✅ 8 Comprehensive Tools: Create, list, update, delete, complete, search tasks, get statistics, and clear completed tasks
- 🔐 Type-Safe: Built with TypeScript and runtime validation using Zod
- 📦 Portable: Uses only official MCP SDK - no vendor lock-in
- 🐳 Dockerized: Ready for containerized deployment
- 💾 Persistent Storage: File-based JSON storage with environment-aware configuration
- 🔍 Advanced Filtering: Filter tasks by status, priority, and category
- 📊 Statistics & Analytics: Track task completion rates, overdue items, and more
- 🎯 Production Ready: Comprehensive error handling and validation
Quick Start
Prerequisites
- Node.js 18+
- npm 9+
Installation
# Clone the repository
git clone https://github.com/aafsar/task-manager-mcp-server.git
cd task-manager-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Run the server
npm start
Development Mode
# Run with hot reload
npm run dev
Available Tools
1. create_task
Create a new task with optional metadata.
Parameters:
title(string, required): Task titledescription(string, optional): Detailed descriptionpriority(enum, optional): "low", "medium", or "high" (default: "medium")category(string, optional): Task category (e.g., "work", "personal")dueDate(string, optional): Due date in YYYY-MM-DD format
Example:
{
"title": "Review pull requests",
"description": "Review open PRs for the API project",
"priority": "high",
"category": "work",
"dueDate": "2025-10-05"
}
2. list_tasks
List tasks with optional filters.
Parameters:
status(enum, optional): "pending", "in_progress", "completed", or "all" (default: "all")priority(enum, optional): "low", "medium", "high", or "all" (default: "all")category(string, optional): Filter by specific category
Example:
{
"status": "pending",
"priority": "high"
}
3. update_task
Update any field of an existing task.
Parameters:
taskId(string, required): Task ID (minimum 8 characters)title(string, optional): New titledescription(string, optional): New descriptionpriority(enum, optional): New prioritycategory(string, optional): New categorydueDate(string, optional): New due datestatus(enum, optional): New status
Example:
{
"taskId": "a1b2c3d4",
"status": "in_progress",
"priority": "high"
}
4. complete_task
Mark a task as completed.
Parameters:
taskId(string, required): Task ID (minimum 8 characters)
5. delete_task
Delete a task permanently.
Parameters:
taskId(string, required): Task ID (minimum 8 characters)
6. search_tasks
Search tasks by title or description.
Parameters:
query(string, required): Search query
Example:
{
"query": "review"
}
7. get_task_stats
Get comprehensive statistics about all tasks.
Returns:
- Total task count
- Completion rate
- Status breakdown (pending/in progress/completed)
- Priority breakdown (high/medium/low)
- Category distribution
- Overdue task count
- Tasks due within 7 days
8. clear_completed
Remove all completed tasks from storage.
Claude Desktop Integration
Configuration
-
Locate your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Add the server configuration:
{
"mcpServers": {
"task-manager": {
"command": "node",
"args": [
"/absolute/path/to/task-manager-mcp-server/dist/index.js"
]
}
}
}
-
Restart Claude Desktop completely
-
Look for the hammer icon (🔨) in the input box
-
Test with: "Create a high priority task called 'Test MCP Integration'"
Testing with MCP Inspector
The MCP Inspector provides a web-based interface for testing tools:
# Launch the inspector
npx @modelcontextprotocol/inspector dist/index.js
This will open a browser window where you can:
- View all available tools
- Test tool execution interactively
- Inspect request/response data
- Debug errors
Docker Deployment
Build and Run with Docker
# Build the image
docker build -t task-manager-mcp .
# Run the container
docker run -it task-manager-mcp
Using Docker Compose
# Start the service
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the service
docker-compose down
Persist Data with Docker
Data is automatically persisted to a Docker volume. To back up your tasks:
# Export tasks
docker cp task-manager-mcp:/app/data/tasks.json ./backup-tasks.json
# Import tasks
docker cp ./backup-tasks.json task-manager-mcp:/app/data/tasks.json
Environment Variables
Configure the server using environment variables:
# Data storage directory (default: ./data)
DATA_DIR=/custom/path/to/data
# Log level
LOG_LEVEL=info
# Node environment
NODE_ENV=production
Create a .env file in the project root:
cp .env.example .env
# Edit .env with your values
Cloud Deployment Options
Railway
# Install Railway CLI
npm install -g @railway/cli
# Login
railway login
# Initialize project
railway init
# Deploy
railway up
Render
- Connect your GitHub repository
- Create a new Web Service
- Set build command:
npm install && npm run build - Set start command:
npm start - Deploy
Fly.io
# Install flyctl
curl -L https://fly.io/install.sh | sh
# Login
flyctl auth login
# Launch app
flyctl launch
# Deploy
flyctl deploy
Project Structure
task-manager-mcp-server/
├── src/
│ ├── index.ts # Main MCP server and request handlers
│ ├── types.ts # TypeScript interfaces and Zod schemas
│ ├── storage.ts # File-based storage module
│ └── tools.ts # Tool implementation functions
├── dist/ # Compiled JavaScript (generated)
├── data/ # Task storage (JSON files, git-ignored)
├── Dockerfile # Docker configuration
├── docker-compose.yml # Docker Compose setup
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This file
Development
Scripts
npm run build # Compile TypeScript to JavaScript
npm run dev # Development mode with hot reload
npm run typecheck # Type check without building
npm run clean # Remove build artifacts
npm start # Run production build
Type Safety
The project uses strict TypeScript settings and Zod for runtime validation:
- Compile-time safety: TypeScript catches type errors during development
- Runtime validation: Zod validates all tool inputs at runtime
- Dual schema approach: JSON Schema for MCP protocol, Zod for validation
Adding New Tools
- Define Zod schema in
src/types.ts - Implement handler function in
src/tools.ts - Add tool definition to
TOOLSarray insrc/index.ts - Add case handler in
tools/callswitch statement - Rebuild and test with MCP Inspector
Troubleshooting
"Cannot find module" errors
Ensure all imports use .js extension (even for .ts files):
import { Task } from "./types.js"; // ✅ Correct
import { Task } from "./types"; // ❌ Wrong
Tasks not persisting
- Check
DATA_DIRenvironment variable - Verify write permissions on data directory
- Check for errors in server logs
TypeScript compilation errors
# Run type checker to identify issues
npm run typecheck
# Common fix: ensure strict types are used
# Check tsconfig.json module settings
MCP Inspector not connecting
- Ensure server builds successfully:
npm run build - Check Node.js version (must be 18+)
- Verify no port conflicts
- Check firewall settings
Claude Desktop not showing tools
- Verify JSON syntax in config file
- Use absolute paths in configuration
- Restart Claude Desktop completely (Cmd+R / Ctrl+R not sufficient)
- Check server logs for errors
Resources
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Support
For issues and questions:
- GitHub Issues: https://github.com/aafsar/task-manager-mcp-server/issues
- MCP Discord: https://discord.gg/modelcontextprotocol