MCP server

live

MDPilot MCP server — setup

Run MDPilot as an MCP server so your AI agent can generate files, check drift, and optimize markdown directly from inside your IDE — without leaving the conversation.

What it is

MDPilot runs as an MCP (Model Context Protocol) server, which means your AI agent can call it as a tool directly from Claude Code, Cursor, Windsurf, or Goose — without opening a browser. The key advantage: the server reads your actual repo on disk, so generated AGENTS.md, CLAUDE.md, and TASK.md files reference real scripts, real file paths, and real dependencies — never guesses.

Prerequisites

1
Node.js 20+
Check with node --version. The MCP server is ESM and requires Node 20 or later.
2
An AI API key — any one of these
GROQ_API_KEYfree tier
Llama 3.3 70B — fast, generous free tier, recommended. console.groq.com →
NVIDIA_API_KEYfree tier
Llama 3.3 70B via NVIDIA API catalog. build.nvidia.com →
ANTHROPIC_API_KEYpaid
Claude 3.5 Haiku. console.anthropic.com →
OPENAI_API_KEYpaid
GPT-4o. platform.openai.com →
The server tries keys in this order: Groq → NVIDIA → Anthropic → OpenAI. Set exactly one. Calls are billed to your key — MDPilot does not proxy them.

No key? The three non-AI tools — analyze_project, optimize_markdown, and check_drift — work without any key. Only the generation tools need one.

Install & configure

Two methods — npx is the recommended one-liner. From source is for contributors or local dev.

Fastest setup

One command — detects your editor, gets you a free API key, writes the config.

Bring your own key or get a free one: works with Groq (free), NVIDIA NIM (free), Anthropic (Claude), or OpenAI.

No account on MDPilot. No billing. Your key stays on your machine.

terminal

$ npx -y mdpilot-mcp setup

Runs interactively — walks you through getting a free Groq key and registers the server for your editor. Or pass flags to skip prompts: --key gsk_… --client claude

Manual setup

Method Anpxrecommended

Add this block to your client's MCP config file. Replace gsk_... with your actual Groq key (or swap the env key for whichever provider you use). No install step — npx pulls the package automatically.

mcp config (Method A — npx)

{
  "mcpServers": {
    "mdpilot": {
      "command": "npx",
      "args": ["-y", "mdpilot-mcp"],
      "env": {
        "GROQ_API_KEY": "gsk_..."
      }
    }
  }
}

Method BFrom sourcecontributors / local dev

Build the package first, then point the config at the compiled output.

1. Build from source

cd packages/mcp
npm install
npm run build
# produces: packages/mcp/dist/index.js

2. mcp config (Method B — from source)

{
  "mcpServers": {
    "mdpilot": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp/dist/index.js"],
      "env": {
        "GROQ_API_KEY": "gsk_..."
      }
    }
  }
}

Replace /absolute/path/to/packages/mcp/dist/index.js with the actual absolute path on your machine.

Per-client setup

Claude Code

Use the CLI shortcut or add the JSON config to ~/.claude/mcp.json.

Claude Code CLI

claude mcp add mdpilot \
  -e GROQ_API_KEY=gsk_... \
  -- npx -y mdpilot-mcp

Switching from local path to npx? Run the CLI command above — it re-registers the connector under the same name mdpilot. Claude reconnects automatically; no need to rename it in the Connectors panel.

Claude Code MCP docs →

Cursor

Open Cursor Settings → MCP → Add new server. Paste the JSON config block from Method A above.

Cursor MCP docs →

Windsurf

Open Windsurf Settings → Cascade → MCP Servers. Add a new entry using the JSON config block from Method A above.

Windsurf MCP docs →

Goose

Add MDPilot as a stdio extension: set type to stdio, command to npx, args to ["-y", "mdpilot-mcp"], and env to your AI provider key (e.g. GROQ_API_KEY).

Goose MCP extensions docs →

The 8 tools

analyze_project

Scan a repo and detect its tech stack, scripts, package manager, and structure. Run this before generate_md_file so output is grounded in real project data.

generate_md_file

Generate a production-grade markdown file (readme, agents, claude, contributing, security, skill, design, context). Reads real package.json scripts — never hallucinates commands. Optionally writes to disk.

generate_task_file

Turn a ticket, Slack thread, or GitHub issue into a structured TASK.md or SPEC.md. Supports execution mode (Guide / AI Exec / Context) and experience level.

explain_code

Generate WALKTHROUGH.md for a file or directory, tuned to any audience: AI agent, team, learner, or non-technical stakeholder.

optimize_markdown

Run the 5-pass token optimizer on any markdown string or file. Strips boilerplate, deduplicates sections, compresses verbose phrasing — typically cuts 20–40% without losing meaning.

image_to_prompt

Analyze an image and generate a precise recreation prompt for FLUX, Stable Diffusion, Midjourney, DALL-E, and Gemini, plus a negative prompt and tag list.

check_drift

Detect where your docs have gone stale relative to the current codebase. Returns a list of sections that reference commands, files, or configs that no longer exist.

update_docs

Patch stale sections in a doc file. Takes the drift report from check_drift and rewrites only the outdated parts, leaving everything else untouched.

Quick start — try it in 60 seconds

Once the server is configured, open any repo in your IDE and try these prompts. Copy and paste them directly into Claude Code, Cursor, or Windsurf.

Generate instruction files

"Use mdpilot to analyze this project and generate an AGENTS.md. Write it to disk."

Calls analyze_project → generate_md_file. References your real scripts and paths.

Turn a task into a prompt

"Use mdpilot to turn this ticket into a TASK.md: [paste your ticket here]"

Calls generate_task_file. Pick execution mode: Guide, AI Exec, or Context.

Explain this codebase

"Use mdpilot to generate a WALKTHROUGH.md for src/lib/auth.ts tuned for a new team member."

Calls explain_code. Audience options: ai_agent, team, learner, non_technical.

Check for stale docs

"Use mdpilot to check my docs for drift, then patch any stale sections."

Calls check_drift → update_docs. Only rewrites outdated parts.

Found a bug or have feedback?

This is a pre-launch tester build. If something breaks or you have suggestions, we want to know.

Report an issue or share feedback →

← Back to docs