Project MCP

What project-mcp MCP server does

project-mcp provides an MCP interface for project documentation and work tracking stored in local files. It recognizes terms such as “project,” “docs,” “plan,” “todos,” “roadmap,” and “status,” then selects relevant sources instead of searching every directory indiscriminately.

The default sources are .project/ for operational information, Markdown files at the repository root, and docs/ for reference material. The server can also initialize the .project/ structure and create or update common project records such as roadmaps, todos, status reports, decisions, and an index file.

How it works

The server runs locally over stdio. Its intent mapping determines which files to search:

• Project-oriented requests search .project/, root files, and docs/.
• Documentation requests search docs/ only.
• Planning and status requests search .project/ only.

Search is only one part of the interface. Tools can list documentation, retrieve a known file, inspect the directory structure, and search tasks by title or content. Other operations modify Markdown files and task records, including adding backlog items, promoting work into active tasks, updating task fields, and generating a TODO dashboard.

Setup and configuration

Install the npm package with npm install project-mcp. Configure an MCP client to launch it through npx -y project-mcp using a local stdio server entry, such as the following:

{
  "mcpServers": {
    "project": {
      "command": "npx",
      "args": ["-y", "project-mcp"]
    }
  }
}

No environment variables are required by the documented setup. After launch, project-mcp discovers and indexes the supported directories automatically.

Tools and capabilities

The documented tool groups cover:

• Searching project sources and reference documentation.
• Reading individual files and listing documentation or categories.
• Initializing project metadata and checking its current state.
• Creating or updating roadmaps, todos, status files, decisions, and index files.
• Creating, updating, filtering, importing, promoting, and removing backlog items.
• Creating, reading, searching, updating, deleting, and archiving tasks.
• Creating and updating documentation, architecture records, and release notes.
• Finding the next dependency-aware task and synchronizing the TODO index.

Use the search tools when an agent needs project context. Use the management tools when the agent is expected to maintain the repository’s planning or task files rather than only read them.

Limitations and notes

Its intent routing depends on the vocabulary mapped to each source group, so queries that do not indicate a project, documentation, planning, or status context may require a more specific tool.

The documented setup exposes project-mcp as a local stdio process. Client-specific configuration beyond the .mcp.json example is not described. The package is distributed under the MIT license.