Promptheus — Claude Code MCP server: refines prompts through questions
MCP server that refines prompts through adaptive clarification questions. Works with six providers: Google, Anthropic, OpenAI, Groq, Qwen, Zhipu.
claude mcp add promptheus -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GROQ_API_KEY=<GROQ_API_KEY> -e QWEN_API_KEY=<QWEN_API_KEY> -e GLM_API_KEY=<GLM_API_KEY> -- uvx promptheusWhat Promptheus does
Promptheus analyzes the initial prompt and asks targeted questions to clarify audience, tone, length, or key requirements. After you answer, it returns a refined prompt. The server exposes two tools: refine_prompt for deep refinement with Q&A and tweak_prompt for surgical edits to an existing prompt.
Inside — support for six LLM backends (Gemini, Claude, GPT-4o, Llama via Groq, Qwen, GLM) and auto-routing through OpenRouter. At least one API key from the provider list is required. The command uvx promptheus starts the server via uvx; Python 3.10+ is mandatory.
The server can skip questions when told to: it then applies direct optimization without dialogue. Prompt history is saved locally; telemetry can be disabled via the PROMPTHEUS_TELEMETRY_ENABLED=0 environment variable.
What it helps with
- refine a prompt through clarification questions before running a task
- switch provider and model mid-session
- apply a surgical edit to a finished prompt without rebuilding it
- check provider availability and API key validity
- track prompt history and reuse past versions
Example prompts for the agent
- Refine the prompt 'Write an article about async programming' and ask questions about audience and tone
- Improve a prompt for technical documentation using Gemini
- Tweak the prompt: add a requirement that the answer must be under 500 words
How to install Promptheus
Platform CLI
claude mcp add promptheus -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GROQ_API_KEY=<GROQ_API_KEY> -e QWEN_API_KEY=<QWEN_API_KEY> -e GLM_API_KEY=<GLM_API_KEY> -- uvx promptheusReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from promptheus <command>
Platform CLI
codex mcp add promptheus --env GOOGLE_API_KEY=<GOOGLE_API_KEY> --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env GROQ_API_KEY=<GROQ_API_KEY> --env QWEN_API_KEY=<QWEN_API_KEY> -- uvx promptheusReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from promptheus <command>
Config file
{
"mcpServers": {
"promptheus": {
"command": "uvx",
"args": [
"promptheus"
],
"env": {
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"GROQ_API_KEY": "<GROQ_API_KEY>",
"QWEN_API_KEY": "<QWEN_API_KEY>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from promptheus <command>
Config file
{
"servers": {
"promptheus": {
"type": "stdio",
"command": "uvx",
"args": [
"promptheus"
],
"env": {
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"GROQ_API_KEY": "<GROQ_API_KEY>",
"QWEN_API_KEY": "<QWEN_API_KEY>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from promptheus <command>
Platform CLI
gemini mcp add -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GROQ_API_KEY=<GROQ_API_KEY> -e QWEN_API_KEY=<QWEN_API_KEY> promptheus uvx promptheusReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from promptheus <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Promptheus
How to install Promptheus in Claude Code?
Run `claude mcp add promptheus -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GROQ_API_KEY=<GROQ_API_KEY> -e QWEN_API_KEY=<QWEN_API_KEY> -e GLM_API_KEY=<GLM_API_KEY> -- uvx promptheus`. Fill in the keys for the providers you plan to use.
What does Promptheus do?
The MCP server improves prompts through adaptive questioning: it detects what information the task needs, asks questions, and assembles a refined prompt. It supports six LLM providers and lets you switch between them during a session.
Which providers does Promptheus support?
Google Gemini, Anthropic Claude, OpenAI GPT, Groq (Llama, Mixtral), Alibaba Qwen, Zhipu GLM, and OpenRouter with auto-routing. At least one API key from this list is required.
