todo-scout
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., "@todo-scout scan ./src for TODO, FIXME, and HACK comments and show per-file counts"
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.
todo-scout-mcp
A tiny MCP server that lets any AI assistant find TODOs, FIXMEs and HACKs in your codebase. Built in the video "MCP Explained in 8 Minutes (Build Your First Server)".
Receipts: about 100 lines of TypeScript · $0 to run (local, no API key) · ~20 min to build.
What it exposes
Type | Name | What it does |
Tool |
| Scans a folder and returns |
Tool |
| Counts items per file, most first |
Resource |
| Triage rules the AI can read |
Related MCP server: devpulse-mcp
Run it
npm install
npm test # builds, starts the server, calls every tool against ./example-projectConnect it to Claude Code
npm run build
claude mcp add todo-scout -- node "$(pwd)/dist/index.js"Then ask: "Use todo-scout to find the FIXMEs in /path/to/my/project and fix the worst one."
Connect it to Claude Desktop / Cursor
Add to the app's MCP config:
{
"mcpServers": {
"todo-scout": { "command": "node", "args": ["/ABSOLUTE/PATH/demo-repo/dist/index.js"] }
}
}The one gotcha
Never console.log in a stdio MCP server. Stdout is the protocol channel, so log to stderr (console.error).
MIT License
Available Tools
2 toolsfind_todosFind TODOsARead-only
Scan a project folder for TODO, FIXME and HACK comments. Returns file, line and comment text.
Inputs: path (required), tags.
todo_statsTODO statsARead-only
Count TODO/FIXME/HACK comments per file, sorted by most first.
Inputs: path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools are closely related since todo_stats is essentially an aggregate view of find_todos output, so an agent could occasionally pick the wrong one when it just needs counts vs. full details. However, the descriptions make the distinction reasonably clear: detailed scan vs. per-file counts.
Both names use snake_case, which is consistent, but the conventions differ slightly (verb-first find_todos vs. noun-first todo_stats). Still readable and predictable enough that an agent can infer behavior from the names.
Two tools is thin for a scanning server; a single scan tool with a mode or filter option could plausibly replace both. It is not egregious, but the surface feels minimal and the second tool is a narrow derivative of the first.
The core lifecycle of scanning and summarizing TODOs is covered, but obvious operations are missing: filtering by tag or severity, excluding directories, or scoping to specific file types. Agents can work around some of this client-side, but the surface is notably limited.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that gives your AI access to the source code and docs of all public github repos
Repository knowledge graph MCP server for codebase understanding and debugging.
Related MCP Servers
- AlicenseAqualityFmaintenanceAn MCP server that allows AI assistants to manage todo lists stored in a simple markdown file, supporting creation, reading, updating, and deletion of todo items with persistent IDs.518 npm6MIT
- AlicenseAqualityBmaintenanceZero-config MCP server that gives AI coding assistants a real-time diagnostic snapshot of your local dev environment. Detects framework, running services, recent errors, git state, and provides a health diagnosis in one call.3532 npm2MIT
- AlicenseAqualityDmaintenanceMCP server that exposes code review tasks from the Fix My Comments VS Code extension to AI agents, enabling them to list, retrieve, reply to, and update task statuses.44 npmMIT
- AlicenseNot gradedqualityDmaintenanceA small MCP server for managing todos, enabling assistants like Claude to create, update, and query task lists through natural conversation. Stores everything in a local SQLite database.13 npm1ISC