ProofHub Server

npm version License: MIT MCP

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:

1. Open ProofHub in a browser
2. Navigate to the task
3. Read the description and all comments
4. Copy relevant bug tracker links (Jira, Linear, GitHub Issues, etc.)
5. 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:

1. Fetch the complete task context
2. Extract Jira/GitHub/Linear links
3. Use your bug tracker MCP to fetch issue details
4. 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