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