@promptprojectmanager/mcp-server

MCP server that exposes Prompt Project Manager prompts and tickets through dual interfaces: Prompts (slash commands) and Tools (AI-discoverable).

Overview

@promptprojectmanager/mcp-server is a standalone npm package that integrates your Prompt Project Manager project with Claude Code, Codex CLI, and Gemini CLI via the Model Context Protocol (MCP).

Authentication

| Mode | Env Variable | Scope | |------|--------------|-------| | Project Token | PPM_PROJECT_TOKEN | Single project (prompts + tickets) |

Project tokens provide scoped access to a single project, including all prompts (via the token owner's account) and ticket management.

Two Interfaces

1. Prompts Interface (Slash Commands) - Explicitly invoke prompts via /ppm:prompt_slug commands
2. Tools Interface (AI Discovery) - AI assistants can discover and invoke prompts/tickets naturally

Features

• Project-Scoped Access - Each token is scoped to one project for security
• Full Prompt Access - Access all prompts from the token owner's account
• Ticket Management - Create, update, close tickets via MCP tools
• Agent Identity - Token name appears in activity logs
• Zero Configuration - Works out of the box with npx

Quick Start

{
  "mcpServers": {
    "ppm": {
      "command": "npx",
      "args": ["@promptprojectmanager/mcp-server@latest"],
      "env": {
        "PPM_PROJECT_TOKEN": "wst_your_token_here"
      }
    }
  }
}

Get your project token from: Project → Agents → Create/View Agent

CLI Arguments

| Argument | Description | |----------|-------------| | --dev | Use development Convex deployment |

Available Tools

Prompt Tools

Each prompt appears as a global tool:

| Tool | Description | |------|-------------| | {prompt_slug} | Execute a specific prompt directly (e.g., code_review) | | system_prompts | List all available prompts | | system_run_prompt | Execute a prompt by slug (for dynamic invocation) |

Ticket Tools

Each project gets ticket management tools:

| Tool | Description | |------|-------------| | {project}_tickets_work | Get next ticket or open specific ticket | | {project}_tickets_close | Mark a ticket as completed | | {project}_tickets_update | Append content to a ticket | | {project}_tickets_create | Create a new ticket | | {project}_tickets_list | List active tickets | | {project}_tickets_get | Get a specific ticket | | {project}_tickets_search | Search tickets by content |

Configuration Examples

Claude Code (JSON)

{
  "mcpServers": {
    "ppm": {
      "command": "npx",
      "args": ["@promptprojectmanager/mcp-server@latest"],
      "env": {
        "PPM_PROJECT_TOKEN": "wst_your_token"
      }
    }
  }
}

Codex CLI (TOML)

[mcp_servers.ppm]
command = "npx"
args = ["@promptprojectmanager/mcp-server@latest"]

[mcp_servers.ppm.env]
PPM_PROJECT_TOKEN = "wst_your_token"

Gemini CLI (JSON)

Same format as Claude Code.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PPM_PROJECT_TOKEN | Yes | Project token (wst_* prefix) for authentication |

Troubleshooting

No Tools Available

1. Verify PPM_PROJECT_TOKEN is set correctly
2. Check token is not revoked in project settings
3. Restart your CLI tool to refresh tools

Stale Content

Restart CLI tool to refresh — prompts are fetched fresh on startup.

Version History

4.2.1 (2026-01-15) - Project Token Only

Breaking Change:

• Removed API key authentication (PPM_API_KEY)
• All authentication now uses project tokens (PPM_PROJECT_TOKEN)
• Removed --projects flag (token is already project-scoped)
• Removed PPM_AGENT (token provides identity directly)

Migration:

• Replace PPM_API_KEY with PPM_PROJECT_TOKEN
• Get project token from Project → Agents section
• Remove --projects flag from args (no longer needed)

4.1.0 - Documentation Update

• Added comprehensive documentation for project token authentication

4.0.0 - Project Tokens & Tickets

• Added PPM_PROJECT_TOKEN authentication mode
• Added ticket management tools per project

Support

• Issues: https://github.com/promptprojectmanager/promptprojectmanager/issues
• Website: https://promptprojectmanager.com

License

MIT License - See LICENSE file for details

Made with ❤️ by the Prompt Project Manager team