The nod-mcp server exposes Nod's git-native project state as MCP tools for managing work items and viewing project plans.
Get project information.
List work items, optionally filtered by cycle, module, or status.
Fetch a single work item by identifier.
Create work items (task by default) with title, type, cycle, module, estimate, priority, and description.
Update work items by identifier: title, branch, module, status, priority, cycle, description, or append to description.
View a kanban board filtered by cycle or module.
View a timeline of cycles.
View the dependency graph.
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., "@nod-mcp add a task to build the note editor in vault, 3h estimate"
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.
Git-native project management for humans and coding agents.
Nod lives in your repository: project state is stored in .nod/nod.db at
the root of the main checkout, so the plan travels with the code. Every git
worktree and subdirectory shares that one database; set NOD_DB to use a
different file. Humans drive it through a focused CLI, coding agents drive
the same state through an MCP server.
# released version from PyPI (both nod and nod-mcp on PATH)
pipx install nod-cli
# bleeding edge, straight from main
pipx install git+https://github.com/neatnettech/nod.gitAfter a PyPI release, update with pipx upgrade nod-cli. For git installs,
run pipx reinstall nod-cli to pick up new commits.
Related MCP server: MCP Project Manager
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
mkdir demo && cd demo
git init
nod initModules group work by area: nod module add "Vault"
Cycles are timeboxed plans: nod cycle add "Sprint 1" --start 2026-10-01 --end 2026-10-14
Work items are epics, stories, tasks, and bugs:
nod task add "Seed categories" --module vault --cycle sprint-1 --estimate 2h
Dependencies order the work: nod depends OSS-2 OSS-1
Branch flow says where the work lives and goes: --branch plus optional
--from-branch (the branch or tag it is cut from) and --to-branch (where it
merges), for example nod task set OSS-2 --from-branch chore/ground --to-branch main
for a long lived branch that lands on main later
Due dates are optional per item: --due 2026-10-16 on task add and task set
(an empty value clears it); an open item past its date shows as OVERDUE in
nod task list and nod graph
nod task list # tabular work items
nod module list # modules
nod cycle list # cycles
nod board # kanban grouped by status
nod timeline # cycles over time with estimates
nod graph # ASCII dependency diagramboard, graph and task list cut by area or release with --module <slug> and
--cycle <slug> (an unknown slug is an error). A filtered graph still names the
prerequisites it does not draw (needs NOD-7 outside this view). Items not yet
placed in a module or a cycle are flagged ORPHANED, and --orphaned shows only them.
On the board each item's ID takes its module's colour and its title ends with its
cycle's letter ([A], [B], in date order); a legend under the board explains the
colours and letters shown. nod board --json names each item's module and cycle.
The dependency graph renders as a tree of prerequisite arrows with status glyphs and branch names:
OSS-1 StateBadge component ✓ DONE ⎇ feat/oss-1-statebadge
OSS-3 Seed categories ○ TODO
├─► OSS-4 Vault home ◐ IN_PROGRESS (depends on this)
└─► OSS-6 Note editor ○ TODO (depends on this)Every view accepts --json for scripting and agents.
nod-mcp exposes the same state as MCP tools: work item create/update/list,
project info, the board, the timeline, and the dependency graph. Point your
MCP client at nod-mcp from inside the repository.
pip install -e ".[dev]"
pytestSchema changes ship as append only MIGRATIONS in
src/nod/infrastructure/database.py, tracked by SQLite's user_version, so an
existing .nod/nod.db upgrades in place on its next command.
Releases: tag a version (v0.1.0-rc.1, then v0.1.0) and push it. The
publish workflow builds the version from the tag and publishes to PyPI via
trusted publishing. Requires Python 3.13+.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle | No | ||
| module | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | task | |
| cycle | No | ||
| title | Yes | ||
| module | No | ||
| estimate | No | ||
| priority | No | medium | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle | No | ||
| module | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle | No | ||
| title | No | ||
| branch | No | ||
| module | No | ||
| status | No | ||
| priority | No | ||
| identifier | Yes | ||
| description | No | ||
| description_append | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0boarddependency_graphproject_gettimelinework_item_creatework_item_getwork_item_listwork_item_updateScored across 8 tools
Most tools have distinct resource+action names (e.g., work_item_list vs work_item_get), but 'board' is a bare noun with unclear scope and could overlap with work_item_list or timeline. The three view-like tools (board, timeline, dependency_graph) are conceptually separate but lack descriptions to clarify boundaries.
Five tools follow a consistent resource_verb pattern (project_get, work_item_list, work_item_get, work_item_create, work_item_update), but 'board', 'timeline', and 'dependency_graph' break that pattern as bare nouns. The mix is readable but not uniform.
Eight tools is a well-scoped number for a project management server, falling comfortably within the ideal 3–15 range. Each tool appears to cover a distinct operation or view without excessive redundancy.
The surface covers create, read (list/get), and update for work items, but lacks a delete operation and any create/list/update for projects (only project_get is present). Board and timeline tools are read-only, which may be acceptable but leaves lifecycle gaps.
Track stories, organize sprints, and manage project workflows across your team
Track issues, projects and dependencies with your agent in a workspace you control.
Durable, shareable and governed project memory with smart triage and explicit project composition.
Project management shared by people and AI agents, with persistent project state through MCP.