Doer MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Doer MCP add 'write release notes' to my sprint list and pin it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
doer-mcp
Official TypeScript-based Model Context Protocol (MCP) server for Doer, the local-first Markdown todoing tool and checklist workbench for developers.
This server enables AI assistants and agents (Antigravity, Claude Desktop, Cursor, and custom MCP clients) to seamlessly search, author, append, toggle checklist items, organize, and pin developer todo lists and sprint goals, manage ActiveStorage file attachments, and render GitHub Flavored Markdown directly through the Doer REST API.
Features
Full MCP Capabilities Suite:
19 Comprehensive Tools: Full CRUD for projects and todo lists, specialized checklist manipulation (
doer_append_to_todo_list,doer_toggle_todo_item), full-text search, pin & reorder management, file attachments, and GFM Markdown rendering.5 MCP Resources: Direct URI inspection via
doer://stats,doer://projects,doer://projects/{id},doer://todo_lists, anddoer://todo_lists/{id}(Markdown with YAML frontmatter).Task Breakdown & Sprint Prompts + Dynamic Sync: Built-in prompts for deconstructing objectives (
doer_breakdown_task), synthesizing project workspaces and planning sprints (doer_plan_project_sprint), and executing{{variable}}checklist templates (doer_use_list_template), plus automatic startup registration of saved Doer todo lists.
Stdio Transport: Ultra-fast JSON-RPC 2.0 communication over standard input/output.
Resilient Attachment Handling: Upload context files via local filesystem paths or base64-encoded strings streamed as
multipart/form-data.OpenAPI 3.1 Contract: Strongly typed client generated directly against Doer's OpenAPI 3.1.0 specification with runtime
Zodvalidation.Zero Friction Setup: Works out of the box with your local Doer Rails server.
Related MCP server: Task MCP Server
Architecture Overview
flowchart LR
Client["AI Agent / Desktop Client<br/>(Antigravity, Claude, Cursor)"]
Stdio["Stdio Transport<br/>(JSON-RPC 2.0)"]
MCPServer["Doer MCP Server<br/>(@modelcontextprotocol/sdk)"]
APIClient["Typed DoerClient<br/>(Node native fetch)"]
DoerAPI["Doer Rails API<br/>(http://localhost:3000/api/v1)"]
Client <-->|MCP Protocol| Stdio
Stdio <--> MCPServer
MCPServer -->|19 Tools / 5 Resources / Prompts| APIClient
APIClient <-->|REST JSON & Multipart| DoerAPIQuickstart
Prerequisites
Node.js:
v18.0.0or higher (recommended: Node 20+)Doer: Running locally (default:
http://localhost:3000)
Installation & Build
# Clone repository
git clone https://github.com/leouofa/doer-mcp.git
cd doer-mcp
# Install dependencies
npm install
# Build the TypeScript distribution
npm run buildConfiguration
The server can be configured via environment variables or command-line arguments:
Option | Environment Variable | CLI Flag | Default | Description |
API URL |
|
|
| Doer API base URL |
API Key |
|
| (none) | Optional Bearer token for authentication |
Timeout |
|
|
| HTTP request timeout in milliseconds |
Template Sync | — |
|
| Eagerly register saved Doer checklists at startup |
Client Integration Guides
1. Antigravity IDE
Add to your local MCP server configuration in Antigravity (~/.gemini/antigravity/mcp_config.json or workspace settings):
{
"mcpServers": {
"doer": {
"command": "node",
"args": ["/Users/leonid/src/doer-mcp/dist/index.js"],
"env": {
"DOER_API_URL": "http://localhost:3000"
}
}
}
}2. Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"doer": {
"command": "node",
"args": ["/path/to/doer-mcp/dist/index.js"],
"env": {
"DOER_API_URL": "http://localhost:3000"
}
}
}
}3. Cursor
Add to your project's .cursor/mcp.json:
{
"mcpServers": {
"doer": {
"command": "node",
"args": ["/path/to/doer-mcp/dist/index.js"],
"env": {
"DOER_API_URL": "http://localhost:3000"
}
}
}
}MCP Primitives Reference
Tools (19)
Project Management
Tool Name | Description | Key Parameters |
| Search and list project workspaces with list counts |
|
| Get project details and all associated todo lists |
|
| Create a new project workspace |
|
| Update project name or description |
|
| Delete a project workspace |
|
Todo Lists & Checklists
Tool Name | Description | Key Parameters |
| Search and list todo lists across projects or standalone |
|
| Retrieve full todo list markdown, pin position, attachments |
|
| Create a new markdown todo list or checklist |
|
| Update title, body, project assignment, or pin position |
|
| Delete a todo list permanently |
|
| Quick toggle pinning of a list to the sidebar |
|
| Update ordered position of pinned todo lists |
|
Checklist Task Manipulation Helpers
Tool Name | Description | Key Parameters |
| Append new task items or sections to an existing list |
|
| Toggle or set task checkbox ( |
|
File Attachments
Tool Name | Description | Key Parameters |
| List context files attached to a todo list |
|
| Attach files from local filesystem paths or base64 data |
|
| Remove an attachment by ID |
|
Markdown & System
Tool Name | Description | Key Parameters |
| Render Markdown to sanitized HTML via Redcarpet |
|
| Retrieve platform aggregate metrics | (none) |
Resources (5)
Resource URI | MIME Type | Description |
|
| Aggregated metrics: total lists, standalone lists, pinned lists, projects, attachments |
|
| Index of all project workspaces |
|
| Detailed view of a project and its associated todo lists |
|
| Index of all active todo lists |
|
| Full todo list Markdown body with YAML frontmatter metadata |
Prompts (3 + Dynamic Sync)
Prompt Name | Arguments | Description |
|
| Interactive workflow decomposing an objective into milestone markdown checklists |
|
| Synthesizes open vs completed checklist items and drafts a sprint plan |
|
| Hydrates any saved checklist template substituting |
Dynamic Sync ( | Variable inputs | Automatically generates native prompts for saved lists containing |
Development
# Generate types from OpenAPI specification
npm run typegen
# Run TypeScript typecheck
npm run typecheck
# Run Vitest test suite
npm test
# Build distribution bundle
npm run buildLicense
MIT © Leonid Medovyy
Available Tools
19 toolsdoer_append_to_todo_listB
Append one or more task items or markdown sections to a todo list (items are automatically formatted as '- [ ] ...')
Inputs: id (required), items (required), section_header, render_markdown.
doer_create_projectC
Create a new project workspace in Doer to organize related todo lists and checklists
Inputs: name (required), description.
doer_create_todo_listB
Create a new markdown todo list or checklist in Doer (assigned to a project or kept standalone)
Inputs: title (required), body, pinned, project_id, +1 more.
doer_delete_attachmentC
Purge and delete a file attachment from a todo list
Inputs: todo_list_id (required), attachment_id (required).
doer_delete_projectC
Delete a project workspace in Doer
Inputs: id (required).
doer_delete_todo_listB
Permanently delete a todo list and its context attachments from Doer
Inputs: id (required).
doer_get_projectB
Get full details of a Doer project workspace, including its associated todo lists and metadata
Inputs: id (required).
doer_get_statsA
Get system statistics from Doer (total todo lists, standalone lists, pinned lists, projects, and attachments)
Inputs: no named parameters.
doer_get_todo_listB
Get a todo list by ID, including its raw markdown body, task checkboxes, pinned position, and optional HTML preview
Inputs: id (required), render_markdown.
doer_list_attachmentsC
List file attachments associated with a todo list in Doer
Inputs: todo_list_id (required).
doer_list_projectsB
List and search todo list projects and workspaces in Doer with list counts and pagination
Inputs: q, limit, offset.
doer_list_todo_listsA
Search and list todo lists with filtering by project, standalone status, pinned status, or keyword
Inputs: q, limit, scope, offset, +2 more.
doer_render_markdownA
Render Markdown text to sanitized HTML using Doer's GitHub-flavored markdown Redcarpet pipeline
Inputs: text (required).
doer_reorder_pinnedC
Update the sequential ordering position of pinned todo lists in the Doer sidebar
Inputs: todo_list_ids (required).
doer_toggle_pinB
Toggle the pinned status of a todo list on the Doer persistent sidebar
Inputs: id (required).
doer_toggle_todo_itemA
Toggle or mark a specific task checklist item (- [ ] / - [x]) in a todo list by 0-based index, line number, or matching text
Inputs: id (required), index, complete, match_text, +2 more.
doer_update_projectC
Update an existing project's name or description in Doer
Inputs: id (required), name, description.
doer_update_todo_listC
Update an existing todo list's title, markdown body, project assignment, or pin state in Doer
Inputs: id (required), body, title, pinned, +3 more.
doer_upload_attachmentB
Upload one or more files to attach to a todo list in Doer (accepts local file paths or base64 data)
Inputs: files (required), todo_list_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools map cleanly to a distinct resource+action (project/list CRUD, attachments, pinning, rendering, stats). Minor overlap exists: doer_update_todo_list can change pin state and markdown body, which partially shadows doer_toggle_pin and doer_append_to_todo_list, but descriptions make the preferred path clear.
All 19 tools use a uniform doer_ prefix with a verb_noun pattern (doer_list_projects, doer_create_todo_list, doer_delete_attachment). The few variations (doer_toggle_pin, doer_reorder_pinned, doer_append_to_todo_list) still follow predictable verb-first phrasing and target the same resource family.
19 tools is on the heavy side of the ideal 3-15 band, but the count is driven by genuine sub-resources: two full CRUD entities (projects, todo lists) plus items, attachments, pinning, and utilities. Each tool covers a distinct operation rather than duplicating another.
Projects and todo lists have full CRUD, attachments have create/read/delete, and utilities (stats, markdown render) round out the surface. Gaps remain around individual task items: you can append and toggle them but there is no delete/remove-item or edit-item tool, and attachments cannot be fetched or renamed.
Maintenance
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI-native task management using plain markdown files to create, update, query, and organize Epics, Stories, Tasks, and Milestones without requiring a database.-
- FlicenseNot gradedqualityDmaintenanceEnables AI clients to manage todo tasks through Tools for adding, listing, completing, and searching, alongside Prompts for daily reviews and task breakdowns. Exposes task lists and statistics as Resources with local JSON file persistence.-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage a local-first Kanban board with Azure DevOps-style workflow rules, including task creation, status updates, subtask breakdown, full-text search, daily summaries, and next-task suggestions.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to maintain a persistent developer logbook with notes, TODOs, reminders, code TODO scanning, and full-text search, while keeping all data local and optionally syncing with Obsidian.79 npm1MIT