Clearpaths MCP Server

An MCP (Model Context Protocol) server that lets AI assistants read and manage your goals in Clearpaths.

Clearpaths is a personal goal tracker that organises goals into areas, tiers, and parent-child hierarchies. This MCP server lets you ask your AI assistant to review your goal tree, add progress notes, reorganise priorities, or track blockers — without leaving the conversation.

Requirements

• Node.js >= 18

Setup

1. Get an API token

Go to your Clearpaths profile → API Tokens → create a token with the abilities you want (e.g. goals:read, goals:write, comments:write).

2. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "clearpaths": {
      "command": "npx",
      "args": ["clearpaths-mcp"],
      "env": {
        "CLEARPATHS_URL": "https://app.clearpaths.pro",
        "CLEARPATHS_TOKEN": "your-api-token-here"
      }
    }
  }
}

Or configure Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "clearpaths": {
      "command": "npx",
      "args": ["clearpaths-mcp"],
      "env": {
        "CLEARPATHS_URL": "https://app.clearpaths.pro",
        "CLEARPATHS_TOKEN": "your-api-token-here"
      }
    }
  }
}

Or run from a local clone

git clone https://github.com/phil-base/clearpaths-mcp.git
cd clearpaths-mcp
npm install
npm run build

Then point your MCP config at the built server:

{
  "mcpServers": {
    "clearpaths": {
      "command": "node",
      "args": ["/absolute/path/to/clearpaths-mcp/dist/index.js"],
      "env": {
        "CLEARPATHS_URL": "https://app.clearpaths.pro",
        "CLEARPATHS_TOKEN": "your-api-token-here"
      }
    }
  }
}

Development

cp .env.example .env  # edit with your URL and token
npm run dev            # runs with tsx (auto-reloads on save)
npm run build          # compile TypeScript to dist/
npm start              # run the compiled server

Tools

Tool	Description
list_goals	List goals with optional filters (status, area, tier, parent)
get_goal	Get detailed info about a goal (children, blockers, notes)
get_goal_tree	Get a goal's full hierarchy as a nested tree
get_summary	Goal counts: total, active, completed, deferred, blocked
list_areas	List areas (life categories) in the current chapter
list_goal_tiers	List goal tiers (hierarchy levels) in the current chapter
create_goal	Create a new goal (root or sub-goal)
update_goal	Update a goal's title, description, area, tier, or parent
delete_goal	Delete a goal and all descendants
complete_goal	Mark a goal as complete (with optional note)
cancel_goal	Cancel a goal (with optional note)
defer_goal	Defer a goal (hide from execution views)
undefer_goal	Bring a deferred goal back to active
block_goal	Mark a goal as blocked by another goal
unblock_goal	Remove a blocking relationship
add_progress_note	Add a progress note to a goal
list_progress_notes	List all progress notes on a goal
what_can_i_do	Actionable leaf goals grouped by area
needs_planning	Leaf goals that need breaking down (not at the lowest tier)
needs_execution	Leaf goals ready to do now (at the lowest tier)
review_area	Area review with completion rollup, stale goals, tree view
break_down_goal	Prepare to decompose a goal into sub-goals at the next tier
what_is_stuck	Blocked goals, stale goals, and highest-impact unblockers
chapter_pulse	Chapter progress: completion by area/tier, recent completions
focus_check	Action distribution vs chapter focus, drift detection

Resources

Resource	URI	Description
Current Chapter	clearpaths://chapters/current	Current chapter info
Blocked Goals	clearpaths://goals/blocked	Goals that are currently blocked
Goal Summary	clearpaths://goals/summary	Counts of goals by status
AI Context	clearpaths://context	Philosophy, guidance, domain model, and current chapter state for AI consumers

Token Abilities

Create tokens with only the abilities you need:

Ability	What it allows
goals:read	List, view, tree, summary
goals:write	Create, update, delete, complete, cancel, defer, block
comments:read	List progress notes
comments:write	Add and delete progress notes
areas:read	List areas
goal-tiers:read	List goal tiers
chapters:read	List and view chapters

For full access, create a token with all abilities or use *.

License

MIT