How do I use claude-augur-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-augur-mcp Show me the decisions in my plan file at ~/.claude/plans/plan.md" 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.

claude-augur-mcp

by Vvkmnn

Overview Schema Related Servers Score Discussions

TypeScript

Local

claude-augur-mcp

A Model Context Protocol (MCP) server for plan reasoning summaries in Claude Code. Surfaces decisions, tradeoffs, and assumptions as scannable abstracts so you can correct Claude's reasoning at a glance.

claude-augur-mcp

npm version License: MIT TypeScript Node.js Claude GitHub stars

Claude's reasoning about plans is invisible. When Claude writes a plan, its decisions, assumptions, and tradeoffs are buried in the document. You have to read the entire thing to find them. If Claude assumed the wrong approach or made a bad tradeoff, you won't know until implementation is underway and something breaks.

Augur reads the plan structure and returns a template that Claude fills with its actual reasoning, inline in the response rather than hidden in a collapsed tool result. You see decisions, assumptions, and tradeoffs at a glance and can correct them before a single line of code is written.

install

Requirements:

Claude Code

From shell:

claude mcp add claude-augur-mcp -- npx claude-augur-mcp

From inside Claude (restart required):

Add this to our global mcp config: npx claude-augur-mcp

Install this mcp: https://github.com/Vvkmnn/claude-augur-mcp

From any manually configurable mcp.json: (Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "claude-augur-mcp": {
      "command": "npx",
      "args": ["claude-augur-mcp"],
      "env": {}
    }
  }
}

There is no npm install required: no external databases, no indexing, only Node.js built-ins for filesystem access.

However, if npx resolves the wrong package, you can force resolution with:

npm install -g claude-augur-mcp

Related MCP server: adr-skills

features

1 tool. Plan structure extraction. Template seeding. Inline rendering.

augur_explain

Read a plan file and return a structured template for Claude to fill with its reasoning. Claude renders the abstract inline in its response, not hidden in a collapsed tool result.

Call after writing or editing a plan file:

augur_explain plan_path="/Users/you/.claude/plans/your-plan.md"

MCP returns two content blocks:

Block 1: one-line summary, visible even when the tool result is collapsed.

your-plan.md · 10/18 done

Block 2: template with pre-rendered header, progress, and [FILL] markers.

┌ 📐 my-project · your-plan.md ────────────────────────────────────
│ Build a REST API with authentication, rate limiting,
│ and WebSocket support for real-time notifications.
│
├ Progress ───────────────────────────────────────────────────────
│ Done (10/18): Auth scaffold, Rate limiter + 1 more
│ Next: WebSocket layer + 1 more
│
├ Decisions ──────────────────────────────────────────────────────
│ [FILL: 2-4 decisions, format: "✓ choice — reason"]
│ [child decisions use: "  └ choice — reason"]
│
├ Assumptions ────────────────────────────────────────────────────
│ [FILL: 1-2 assumptions, format: "? statement"]
│
├ Tradeoffs ──────────────────────────────────────────────────────
│ [FILL: 1-2 lines, "+" for pro, "−" for con]
│
├ Reasoning ──────────────────────────────────────────────────────
│ [FILL: 2-3 lines explaining WHY]
└──────────────────────────────────────────────────────────────────

Claude fills the template inline:

┌ 📐 my-project · your-plan.md ────────────────────────────────────
│ Build a REST API with authentication, rate limiting,
│ and WebSocket support for real-time notifications.
│
├ Progress ───────────────────────────────────────────────────────
│ Done (10/18): Auth scaffold, Rate limiter + 1 more
│ Next: WebSocket layer + 1 more
│
├ Decisions ──────────────────────────────────────────────────────
│ ✓ Express over Fastify — team familiarity, middleware ecosystem
│   └ Passport.js for auth — proven, supports OAuth + JWT
│ ✓ Redis for rate limiting — atomic counters, TTL built-in
│ ✓ ws over Socket.io — lighter, no fallback polling needed
│
├ Assumptions ────────────────────────────────────────────────────
│ ? Single Redis instance sufficient for current scale
│ ? WebSocket clients handle reconnection gracefully
│
├ Tradeoffs ──────────────────────────────────────────────────────
│ + Redis rate limiting: sub-ms response, horizontal scaling
│ − Extra infrastructure dependency to operate
│
├ Reasoning ──────────────────────────────────────────────────────
│ Auth must be production-grade from day one — Passport.js
│ handles OAuth/JWT without custom crypto. Redis rate limiting
│ chosen over in-memory because the API will be multi-process.
│ ws chosen over Socket.io to avoid 200KB bundle overhead.
└──────────────────────────────────────────────────────────────────

What gets extracted from the plan file:

Field	Source	Example
Project name	H1 title before `:`	`my-project`
Purpose	First `Primary goal:` line, or first prose paragraph	Full text, word-wrapped
Sections	H2 headings (excluding `Detail:` sections)	`Context, Architecture, ...`
Progress	`### Step N:` headings with `- [x]` / `- [ ]` counts	`Done (10/18): Auth, Rate limiter`
Done steps	Steps where all items are `[x]`	Capped at 2 names + `N more`
Next steps	Steps with pending items	First name + `N more`

methodology

How claude-augur-mcp reads plans:

                    📐 claude-augur-mcp
                    ━━━━━━━━━━━━━━━━━━━

              Claude writes a plan
                augur_explain
                    │
                    ▼
              ┌─────────────────┐
              │  read plan file │  from disk (read-only)
              │  (session.ts)   │
              └────────┬────────┘
                       │
                       ├── title → project name (before ":")
                       ├── purpose → **Primary goal**: or first prose
                       ├── sections → H2 headings
                       └── progress → ### Step N: with [x]/[ ] counts
                       │
              ┌────────▼────────┐
              │ render template │  left-gutter format
              │ (render.ts)     │  [FILL] markers for Claude
              └────────┬────────┘
                       │
          ┌────────────┴────────────┐
          ▼                         ▼
     block 1                   block 2
     summary                   template
     (visible collapsed)       (Claude renders inline)
          │                         │
          ▼                         ▼
     plan.md · 10/18 done      ┌ 📐 project · plan.md ──
                               │ purpose...
                               ├ Progress ────────────
                               │ Done (10/18): Auth + 1
                               ├ Decisions ───────────
                               │ [FILL]
                               ├ Assumptions ─────────
                               │ [FILL]
                               └──────────────────────


     TEMPLATE SEEDING:

     Regex extraction of Claude's thinking blocks produces garbage:
     free-form prose has no structured patterns to match.

     Augur takes a different approach: extract plan structure (the
     deterministic part), seed a template, let Claude fill reasoning
     (the part only Claude knows). Structure from MCP, content from
     Claude. Consistent format, accurate reasoning.

     MCP pre-renders              Claude fills
     ──────────────               ────────────
     header + purpose             decisions
     progress counts              assumptions
     section labels               tradeoffs
     formatting rules             reasoning

Two-block return: MCP tool results get collapsed in Claude Code UI. Block 1 is a one-line summary visible even when collapsed. Block 2 is the full template that Claude renders inline in its response, visible to the user without expanding.

Read-only: augur_explain only reads the plan file. No disk writes, no state, no side effects. Works in plan mode.

Architecture:

claude-augur-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts       # MCP server, 1 tool
│   ├── types.ts       # PlanStructure interface
│   ├── session.ts     # Plan file parser + step progress extractor
│   └── render.ts      # Template generator with left-gutter format
└── demo/
    ├── demo.cast      # asciinema recording
    └── demo.gif       # animated demo

Design principles:

Template seeding over regex extraction: regex on thinking blocks produced garbage; template seeding lets Claude fill its own reasoning accurately
Inline over collapsed: tool results get collapsed in Claude Code UI; inline rendering keeps the abstract visible
Read-only: no disk writes, no state, works in plan mode
Single tool: augur_explain does one thing well; no CRUD, no storage, no insight management
Left-gutter format: ┌│├└ vertical bar with no right border; can't misalign, renders cleanly in any terminal width
Never truncate: purpose and header always render in full; word-wrapped, never cut

Design influences:

Architecture Decision Records: structured format for capturing decisions with context and consequences
Y-Statement ADR variant: concise decision format: "In context X, facing Y, we decided Z, accepting C"
Roman Augurs: priests who interpreted signs and patterns to reveal meaning hidden from ordinary observation

development

git clone https://github.com/Vvkmnn/claude-augur-mcp && cd claude-augur-mcp
npm install && npm run build

Scripts:

Command	Description
`npm run build`	TypeScript compilation (`tsc && chmod +x dist/index.js`)
`npm run dev`	Watch mode (`tsc --watch`)
`npm start`	Run MCP server (`node dist/index.js`)
`npm run clean`	Remove build artifacts (`rm -rf dist`)
`npm run typecheck`	TypeScript validation without emit
`npm test`	Type-check

Contributing:

Fork the repository and create feature branches
Follow TypeScript strict mode and MCP protocol standards

Learn from examples:

Official MCP servers for reference implementations
TypeScript SDK for best practices
Creating Node.js modules for npm package development

license

MIT

Tomb of the Augurs, fresco (Tarquinia, ~530 BCE). Claudius, emperor, scholar, and member of the Augural College, wrote Tyrrenika, a lost 20-volume history of Etruscan civilization and their methods of divination. The augurs' role was not to predict the future, but to interpret the signs and reveal whether a proposed course of action had merit.

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Vvkmnn/claude-augur-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server