instruction-mcp

A minimal MCP server that serves markdown instructions as tools.

Why?

LLMs work better with context. Instead of copy-pasting instructions into every conversation, define them once and deliver them to all your LLM applications — Claude Desktop, Claude Code, and any MCP-compatible client.

Use cases:

• Team playbooks — Coding standards, review checklists, incident response
• Domain knowledge — Data dictionaries, API conventions, business rules
• Personal workflows — Analysis templates, writing guides, debugging steps

No UI, no database — just a YAML config and markdown files. Version control your instructions with git, share them across your team.

How It Works

1. Define tools in instruction.yaml pointing to markdown files
2. Run the MCP server
3. Claude sees your tools and calls them based on conversation context
4. Tool returns the markdown content
5. Claude uses the instructions to help with your task

Understanding Tool Behavior

Tool descriptions determine when Claude calls the tool. Claude reads all available tool descriptions and picks the relevant one based on your prompt.

Tool responses are context, not commands. When a tool returns markdown, it's added to the conversation like any other text. Claude doesn't automatically "follow" it — your prompt determines that.

Retrieval vs Action

# Just retrieves and summarizes
"What's our code review process?"

# Retrieves AND follows the instructions
"Review this PR following our code review process"

The word "following" makes Claude apply the instructions rather than just report them.

Being Explicit

For guaranteed results, name the tool directly:

"Use get_code_review to review this PR and follow the checklist"

This ensures:

1. The tool is called (no relying on description matching)
2. The instructions are followed (not just retrieved)

Quick Start

1. Create your config

# instruction.yaml
version: "1"

tools:
  get_coding_standards:
    title: "Coding Standards"
    description: "Team coding standards and best practices"
    default: "general"
    instructions:
      general: "resources/standards/general.md"
      typescript: "resources/standards/typescript.md"
      testing: "resources/standards/testing.md"

2. Add your markdown files

my-instructions/
├── instruction.yaml
└── resources/
    └── standards/
        ├── general.md
        ├── typescript.md
        └── testing.md

3. Validate

npx instruction-mcp validate -c instruction.yaml

4. Add to Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-instructions": {
      "command": "npx",
      "args": ["instruction-mcp", "-c", "instruction.yaml"],
      "cwd": "/absolute/path/to/my-instructions"
    }
  }
}

5. Use in Claude

"Review this PR for me"

Claude will call get_coding_standards and use your team's standards to review the code.

CLI

# Validate config and check all files exist
npx instruction-mcp validate -c instruction.yaml

# List all tools and instructions
npx instruction-mcp list -c instruction.yaml

# Start server (stdio mode)
npx instruction-mcp -c instruction.yaml

Config Reference

version: "1"

tools:
  tool_name:                    # Tool name exposed to Claude
    title: "Human Title"        # Display name
    description: "..."          # Helps Claude decide when to use this tool
    default: "key"              # Optional: default if no instruction specified
    instructions:
      key1: "path/to/file.md"   # Instruction key -> markdown file
      key2: "path/to/other.md"

Field	Type	Required	Description
title	string	yes	Human-readable tool name
description	string	yes	Description for Claude's tool selection
default	string	no	Default instruction key
instructions	map	yes	Key-value pairs of name: filepath

Example

See example/ for a complete working setup with analyst playbooks and code review checklists, including Docker deployment.

License

MIT