PromptKiln MCP Server

Two-pass prompt optimization with local heuristic analysis and LLM-specific best practices

PromptKiln applies a Double Forge process to transform rough prompts into high-quality, structured instructions tuned for the LLM you actually use.

Features

• Double Forge two-pass optimization (heuristic analysis + LLM refinement)
• LLM-specific best practices for Claude, Gemini, and OpenAI models
• Self-updating cache that keeps best-practice data fresh
• Heuristic scoring to quantify prompt quality before and after optimization
• Presets for common prompt patterns (code review, creative writing, data analysis, etc.)

Quick Start

Option A: npx (recommended)

npx promptkiln-mcp

Add to your MCP client configuration:

{
  "mcpServers": {
    "promptkiln": {
      "command": "npx",
      "args": ["-y", "promptkiln-mcp"]
    }
  }
}

Option B: Claude Code plugin

claude plugin install promptkiln-mcp

Option C: Manual install

git clone https://github.com/alanshurafa/promptkiln-mcp.git
cd promptkiln-mcp
npm install
node server.js

Tools

| Tool | Description | |---|---| | double_forge | Run the full two-pass optimization pipeline on a prompt | | score | Score a prompt using heuristic analysis without modifying it | | list_presets | List available optimization presets | | forge_with_preset | Optimize a prompt using a named preset configuration | | update_practices | Refresh the LLM best-practices cache from upstream sources |

Target LLM Options

| Value | Aliases | Description | |---|---|---| | claude | anthropic, sonnet, opus, haiku | Anthropic Claude models | | gemini | google, bard, gemini-pro, gemini-flash | Google Gemini models | | openai | gpt, chatgpt, gpt-4, gpt-4o, o1, o3 | OpenAI GPT models | | universal | (default) | Model-agnostic optimization |

How It Works

PromptKiln uses a Double Forge architecture with two distinct passes:

Pass 1 -- Heuristic Analysis

The prompt is scored locally against a set of structural and semantic heuristics: clarity, specificity, role definition, output format, constraint coverage, and more. This pass runs instantly with no API calls and produces a numeric score, a list of identified gaps, and a heuristic-improved version of the prompt.

Pass 2 -- LLM Refinement

The heuristic output is fed into a refinement prompt that applies LLM-specific best practices for the target model. This pass restructures the prompt using the optimal patterns, token strategies, and formatting conventions for the chosen LLM, producing the final optimized prompt.

Self-Updating Best Practices

PromptKiln maintains best-practice data through a three-tier architecture:

1. Bundled defaults -- shipped with the package, always available offline
2. Cached upstream data -- periodically refreshed from curated sources and stored in llm-practices-cache.json
3. User overrides -- local customizations that take highest priority

Run update_practices to pull the latest recommendations, or let the cache refresh automatically when it expires.

License

MIT