MCP (Model Context Protocol) server for md2do task manager
npm install @md2do/mcp


MCP (Model Context Protocol) server for md2do task manager. This allows AI assistants like Claude Code to directly
query and analyze your markdown tasks.
The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with external tools and
data sources. This MCP server exposes md2do's task management capabilities to any MCP-compatible client.
- list_tasks - Query tasks with filters (assignee, priority, tags, due dates) and sorting
- get_task_stats - Get aggregated statistics grouped by assignee, project, priority, etc.
- search_tasks - Full-text search in task descriptions
- get_task_by_id - Retrieve a single task by its ID
- task://all - All tasks in workspace
- task://project/{name} - Tasks for a specific project
- task://person/{name} - Tasks for a specific person
- task://file/{path} - Tasks from a specific file
- daily_standup - Generate daily standup report
- sprint_summary - Summarize sprint progress
- overdue_review - Review and prioritize overdue tasks
The MCP server is included in the md2do monorepo. Build it with:
``bash`
pnpm --filter @md2do/mcp build
Add the MCP server to your Claude Code settings:
Edit ~/.config/claude-code/settings.json and add:
`json`
{
"mcpServers": {
"md2do": {
"command": "node",
"args": ["/path/to/md2do/packages/mcp/dist/index.js"],
"env": {}
}
}
}
Edit %APPDATA%\claude-code\settings.json and add:
`json`
{
"mcpServers": {
"md2do": {
"command": "node",
"args": ["C:\\path\\to\\md2do\\packages\\mcp\\dist\\index.js"],
"env": {}
}
}
}
Once configured, you can ask Claude to query your tasks:
`
You: "What urgent tasks does @nick have?"
Claude calls: list_tasks({assignee: "nick", priority: "urgent"})
Claude: "Nick has 3 urgent tasks:
- Fix memory leak in WebSocket connection (due Jan 18)
- Implement user authentication API (due Jan 20)
- Set up staging environment (due Jan 18)"
`
`
You: "Show me task breakdown by assignee"
Claude calls: get_task_stats({groupBy: "assignee"})
Claude: "Here's the task breakdown:
- @nick: 19 tasks (4 completed, 15 incomplete)
- @jane: 19 tasks (4 completed, 15 incomplete)
- @alex: 9 tasks (1 completed, 8 incomplete)
..."
`
`
You: "Find all tasks mentioning authentication"
Claude calls: search_tasks({query: "authentication", caseInsensitive: true})
Claude: "Found 5 tasks mentioning authentication:
1. Implement user authentication API
2. Add OAuth authentication flow
3. Test authentication on mobile
..."
`
`
You: "Generate my daily standup"
Claude uses: daily_standup prompt
Claude: "Daily Standup Report
Yesterday:
- ā
Set up PostgreSQL database schema
- ā
Configure CI/CD pipeline
Today:
- š² Fix memory leak in WebSocket connection (HIGH PRIORITY)
- š² Implement user authentication API
Blockers:
- Need design approval for login forms"
`
Access task data via URIs:
`
Claude: "Show me all tasks for the acme-app project"
Uses resource: task://project/acme-app
Claude displays all tasks filtered by project
`
`bashWatch mode
pnpm --filter @md2do/mcp dev
$3
`bash
Run tests
pnpm --filter @md2do/mcp testRun tests in watch mode
pnpm --filter @md2do/mcp test
`Architecture
The MCP server runs as a local process and communicates via stdio (standard input/output):
`
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
ā Claude Code ā āāāāāāāŗ ā md2do-mcp ā āāāāāāāŗ ā Your markdown ā
ā (MCP Client) ā stdio ā (MCP Server) ā ā files ā
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
`Resource Usage:
- Memory: ~10-50MB
- CPU: Negligible (only active when queried)
- Network: None (local stdio only)
Troubleshooting
$3
1. Check that Node.js >= 18.0.0 is installed:
`bash
node --version
`2. Verify the build was successful:
`bash
ls -la packages/mcp/dist/index.js
`3. Test the server manually:
`bash
node packages/mcp/dist/index.js
`$3
1. Check your settings.json path is correct
2. Verify the absolute path to dist/index.js
3. Restart Claude Code after changing settings
$3
On Unix systems, ensure the file is executable:
`bash
chmod +x packages/mcp/dist/index.js
`API Reference
$3
Input:
`typescript
{
path?: string; // Path to scan (defaults to cwd)
assignee?: string; // Filter by assignee
priority?: 'urgent' | 'high' | 'normal' | 'low';
project?: string; // Filter by project
person?: string; // Filter by person
tag?: string; // Filter by tag
completed?: boolean; // Filter by completion status
overdue?: boolean; // Show only overdue tasks
dueToday?: boolean; // Show tasks due today
dueThisWeek?: boolean; // Show tasks due this week
dueWithin?: number; // Show tasks due within N days
sort?: 'due' | 'priority' | 'created' | 'file' | 'project' | 'assignee';
reverse?: boolean; // Reverse sort order
limit?: number; // Limit results
}
`Output:
`json
{
"tasks": [...],
"metadata": {
"total": 113,
"completed": 21,
"incomplete": 92
}
}
`$3
Input:
`typescript
{
path?: string;
groupBy?: 'assignee' | 'project' | 'person' | 'priority' | 'tag';
assignee?: string; // Pre-filter
project?: string; // Pre-filter
}
`Output:
`json
{
"overall": {
"filesScanned": 8,
"totalTasks": 113,
"completed": 21,
"incomplete": 92,
"overdue": 5
},
"byPriority": {...},
"byAssignee": {...},
"byProject": {...}
}
`$3
Input:
`typescript
{
path?: string;
query: string; // Required
caseInsensitive?: boolean;
limit?: number;
}
`$3
Input:
`typescript
{
path?: string;
id: string; // Required
}
``MIT - See root LICENSE file