home / mcp / mcp prompt manager mcp server

MCP Prompt Manager MCP Server

Provides Git-driven prompt templates for MCP clients, with hot-reload, group-based loading, and Handlebars templates.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "carllee1983-mcp-prompt-manager": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-prompt-manager/dist/index.js"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "GIT_BRANCH": "main",
        "MCP_GROUPS": "common",
        "STORAGE_DIR": ".prompts_cache",
        "MCP_LANGUAGE": "en",
        "GIT_MAX_RETRIES": "3",
        "PROMPT_REPO_URL": "<path-or-url-to-prompts>",
        "CACHE_CLEANUP_INTERVAL": "10000"
      }
    }
  }
}

You run an MCP server that fetches and serves prompt templates from a Git repository. It lets you load and render dynamic prompts in MCP clients, supports hot-reload, group-based loading, and provides health and usage statistics so your team can collaborate on prompts with confidence.

How to use

Install and run the MCP Prompt Manager locally, then connect your MCP client (Cursor, Claude Desktop, VS Code, etc.) to it. You’ll load prompts from a Git repo, use Handlebars templates and partials, and benefit from hot-reload without restarting the server. You can filter by prompt groups, inspect loaded prompts, preview renderings, and monitor system health and statistics.

How to install

# Prerequisites
- Node.js 18 or higher
- pnpm 8 or higher
- Git

# Option 1. Marketplace Installation (easiest)
# Follow the marketplace workflow to install the MCP server, then locate the installation path for dist/index.js

Option 1 covers marketplace installation. After installation, configure your MCP client to point at the locally installed server using the absolute path to dist/index.js.

# Option 2. Docker Deployment (recommended for production)
# 1. Clone the repository
git clone <project URL>
cd mcp-prompt-manager

# 2. Copy environment variables example
cp .env.docker.example .env

# 3. Edit .env and set your Git repository URL
# PROMPT_REPO_URL=https://github.com/yourusername/your-prompts-repo.git

# 4. Start with Docker Compose
docker-compose up -d

# 5. View logs
docker-compose logs -f

Option 2 uses Docker Compose to run the server. After starting, you can monitor logs to verify that prompts are loaded.

# Option 3. Local Installation (development / full control)

# 1. Clone the repository
git clone https://github.com/CarlLee1983/mcp-prompt-manager.git
cd mcp-prompt-manager

# 2. Install dependencies (pnpm is required)
pnpm install

# 3. Build the project
pnpm run build

# 4. Configure environment variables
cp .env.example .env
# Edit .env to set PROMPT_REPO_URL and other vars as needed

# 5. Start the server (production)
pnpm start

Configuration and how the server runs

When you run the server locally, you execute the compiled JavaScript file with Node. The configuration must point your MCP client to the absolute path of the compiled entry point and include the necessary environment variables.

{
  "mcpServers": {
    "mcp_prompt_manager": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
      "env": {
        "PROMPT_REPO_URL": "/path/to/your/prompts",
        "MCP_LANGUAGE": "en",
        "MCP_GROUPS": "common,laravel,vue",
        "STORAGE_DIR": ".prompts_cache",
        "GIT_BRANCH": "main",
        "GIT_MAX_RETRIES": "3",
        "CACHE_CLEANUP_INTERVAL": "10000",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Security and best practices

Keep sensitive values out of version control. Use SSH keys for Git access where possible. Treat the .env file as a template when sharing configuration. Ensure paths used in configuration are absolute and valid on the host running the MCP client.

Troubleshooting and notes

If no prompts load, verify the PROMPT_REPO_URL is correct and that MCP_GROUPS includes the desired groups. Check runtime logs for default group behavior when MCP_GROUPS is not set. Enable LOG_LEVEL=debug to get detailed information about which groups are loaded.

To reload prompts without restarting the server, use the mcp.reload tool. To inspect a specific prompt, use mcp.inspect. Use preview_prompt to render a template with given arguments without sending it to an LLM.

Guidance on prompt repository layout

Organize prompts under a repository with a clear group structure. Include a root set and a common group that loads by default. Other groups load only when specified in MCP_GROUPS. A registry.yaml file is optional and can control prompt visibility and deprecation.

Prominent MCP tools and resources

Reload prompts without restarting: mcp.reload or mcp.reload_prompts. Get prompts statistics with mcp.stats or mcp.prompt.stats. List prompts with mcp.list or mcp.prompt.list using optional filters. Inspect a prompt with mcp.inspect. Switch repositories with mcp.repo.switch. Preview prompt templates with preview_prompt to see rendered output and token estimates.

Development and testing guide

Compile TypeScript and run the inspector to test prompts during development. Use inspector:dev for automatic compilation and inspection workflow. Run tests and ensure code quality with lint and format tooling. Use the provided test suite to verify behavior and performance.

Available tools

mcp.reload

Reload all prompts from the Git repository without restarting the server, clears cache, and reloads templates.

mcp.stats

Return statistics about prompts, including counts by runtime state.

mcp.list

List prompts with filters for status, group, tag, and runtime state.

mcp.inspect

Inspect detailed runtime metadata for a specific prompt by ID.

mcp.repo.switch

Switch to a different Prompt repository URL and reload prompts without downtime.

preview_prompt

Render a prompt template with supplied arguments without sending to an LLM to verify logic and token usage.