🔌 ProofHub MCP Server

A Model Context Protocol (MCP) server that bridges ProofHub's project management capabilities with AI assistants like Claude, GitHub Copilot, and Cursor. Paste a ProofHub task URL in your AI chat, and the agent automatically fetches task details, comments, and bug tracker links to help you complete development tasks faster.

🎯 What This Solves

As a developer working with ProofHub for task management, you normally have to:

Open ProofHub in a browser
Navigate to the task
Read the description and all comments
Copy relevant bug tracker links (Jira, Linear, GitHub Issues, etc.)
Context-switch back to your code editor

With this MCP server, simply paste the ProofHub URL into your AI assistant, and it automatically:

✅ Fetches the complete task description
✅ Retrieves all comments and history
✅ Extracts bug tracker links from anywhere in the task
✅ Provides structured context for the AI to help you code

⚡ Features

🔒 Secure: API key stored in environment variables, never in code
⏱️ Rate Limit Handling: Automatically respects ProofHub's 25 req/10s limit with retry logic
🧹 HTML Cleanup: Strips HTML tags from descriptions/comments for clean AI consumption
🔗 Smart Link Extraction: Regex patterns detect bug tracker URLs across all text fields
🎯 One-Shot Tool: get_task_with_bug_links fetches everything in a single call
🛡️ Error Handling: Graceful error messages with API status codes

🚀 Quick Start

1. Installation

npm install

2. Configuration

Create a .env file (use .env.example as template):

PROOFHUB_API_KEY=your_api_key_here
PROOFHUB_API_BASE=https://company.proofhub.com/api/v3

Getting your API key: Log in to ProofHub → Account Settings → Apps & Integrations → API → Generate new API key

3. Connect to Your AI Assistant

🤖 Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "proofhub": {
      "command": "node",
      "args": ["/absolute/path/to/proofhub-mcp/index.js"],
      "env": {
        "PROOFHUB_API_KEY": "your_key_here"
      }
    }
  }
}

Config location:

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

💻 VS Code Copilot

Add to .vscode/mcp.json in your workspace or user settings:

{
  "servers": {
    "proofhub": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/proofhub-mcp/index.js"],
      "env": {
        "PROOFHUB_API_KEY": "your_key_here"
      }
    }
  }
}

📋 Available Tools

Tool	Description	Use Case
`proofhub_parse_url`	Extracts project/list/task IDs from a ProofHub URL	Parse URL before calling other tools
`proofhub_get_task`	Fetches complete task details (title, description, stage, custom fields, assignees)	Get full task context
`proofhub_get_comments`	Retrieves all task comments with timestamps	Review team discussions
`proofhub_get_task_with_bug_links`	⭐ One-shot: Fetches task + comments + auto-extracts bug tracker URLs	Most useful - get everything in one call
`proofhub_create_comment`	Posts a new comment on a task	Update task from your AI chat
`proofhub_get_task_history`	Fetches activity/stage change history	Track task evolution

💡 Usage Examples

Example 1: Fetch Task Context

Simply paste a ProofHub URL in your AI chat:

Get context for this task:
https://kpi.proofhub.com/bappswift/#app/todos/project-7189443252/list-270280503800/task-514774338823

The AI will call proofhub_get_task_with_bug_links and return:

Task title and description
All comments (cleaned from HTML)
List of bug tracker links found
Stage, assignees, and custom fields

Example 2: Development Workflow

I need to work on this ProofHub task:
https://kpi.proofhub.com/.../task-514774338823

Fetch the task, find any Jira links, and help me understand what needs to be built.

The AI will:

Fetch the complete task context
Extract Jira/GitHub/Linear links
Use your bug tracker MCP to fetch issue details
Provide a comprehensive development plan

Example 3: Update Task

Add a comment to task 514774338823 in project 7189443252, list 270280503800:
"Completed the API endpoint implementation. Ready for review."

🤝 Contributing

Contributions welcome! Fork the repo, make your changes, and submit a pull request.

References

ProofHub API v3

ProofHub MCP Server