Productplan MCP Server

1. Locate your config file:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Open it in any text editor and add the following (replace your-token with your actual API token):

Mac/Linux:

{
  "mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

3. Restart Claude Desktop.

Add the following to your config file:

• Mac/Linux: ~/.claude.json
• Windows: %USERPROFILE%\.claude.json

Mac/Linux:

{
  "mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

1. Open Cursor.
2. Navigate to Settings → MCP Servers.
3. Add the following configuration:

Mac/Linux:

{
  "productplan": {
    "command": "/usr/local/bin/productplan",
    "env": {
      "PRODUCTPLAN_API_TOKEN": "your-token"
    }
  }
}

Windows:

{
  "productplan": {
    "command": "C:\\Tools\\productplan.exe",
    "env": {
      "PRODUCTPLAN_API_TOKEN": "your-token"
    }
  }
}

Windows users: Use double backslashes (\\) in the path. This is required because backslash is an escape character in JSON.

1. Install the Cline extension.
2. Open VS Code settings (JSON) and add:

Mac/Linux:

{
  "cline.mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows:

{
  "cline.mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

1. Install the Continue extension.
2. Add the following to your config file:
   • Mac/Linux: ~/.continue/config.json
   • Windows: %USERPROFILE%\.continue\config.json

Mac/Linux:

{
  "mcpServers": [
    {
      "name": "productplan",
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  ]
}

Windows:

{
  "mcpServers": [
    {
      "name": "productplan",
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  ]
}

1. Set the environment variable on your n8n instance:

   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
   

2. Add an MCP Client node to your workflow.
3. Configure:
   • Command:
     • Mac/Linux: /usr/local/bin/productplan
     • Windows: C:\Tools\productplan.exe
   • Environment Variables: PRODUCTPLAN_API_TOKEN=your-token
4. Connect to an AI Agent node.

Example workflow: Slack Trigger → AI Agent (with MCP Client) → Slack Response

productplan-mcp-server/
├── cmd/productplan/main.go      # Entry point (~100 lines)
├── internal/
│   ├── api/                     # ProductPlan API client
│   │   ├── client.go            # HTTP client with caching, retry, rate limiting
│   │   ├── endpoints.go         # 40+ API endpoint methods
│   │   └── formatters.go        # Response enrichment for AI
│   ├── mcp/                     # MCP protocol implementation
│   │   ├── server.go            # JSON-RPC server, stdio I/O
│   │   ├── handler.go           # Tool dispatch via registry
│   │   └── types.go             # Protocol types
│   ├── tools/                   # Tool definitions and handlers
│   │   ├── registry.go          # Tool registration and dispatch
│   │   └── types.go             # Typed argument structs for handlers
│   ├── cli/                     # CLI commands (status, roadmaps, etc.)
│   │   └── cli.go
│   └── logging/                 # Structured JSON logging
│       └── logger.go
├── pkg/productplan/             # Reusable utilities
│   ├── cache.go                 # LRU cache with TTL
│   ├── retry.go                 # Exponential backoff with jitter
│   ├── ratelimit.go             # Adaptive rate limiting
│   ├── registry.go              # ToolBuilder for schema generation
│   ├── requestid.go             # Request tracing
│   └── errors.go                # Error suggestions
└── evals/                       # LLM evaluation test suite
    ├── tool_selection.json
    ├── confusion_pairs.json
    └── argument_correctness.json

git clone https://github.com/olgasafonova/productplan-mcp-server.git
cd productplan-mcp-server
go build -o productplan ./cmd/productplan

Build for all platforms:

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o dist/productplan-darwin-arm64 ./cmd/productplan

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o dist/productplan-darwin-amd64 ./cmd/productplan

# Linux
GOOS=linux GOARCH=amd64 go build -o dist/productplan-linux-amd64 ./cmd/productplan

# Windows
GOOS=windows GOARCH=amd64 go build -o dist/productplan-windows-amd64.exe ./cmd/productplan

Run all tests:

go test ./...

Run with coverage:

go test ./... -cover

Run benchmarks:

go test ./internal/... -bench=. -benchmem

Run evaluation suite:

./scripts/run-evals.sh

Coverage targets:

47 tools are available: 35 READ tools and 12 WRITE tools (action - based):

Read tools:

• Roadmaps: list_roadmaps, get_roadmap, get_roadmap_bars, get_roadmap_lanes, get_roadmap_milestones, get_roadmap_legends, get_roadmap_comments, get_roadmap_complete
• Bars: get_bar, get_bar_children, get_bar_comments, get_bar_connections, get_bar_links
• OKRs: list_objectives, get_objective, list_key_results, get_key_result
• Discovery: list_ideas, get_idea, list_all_customers, list_all_tags, list_opportunities, get_opportunity, list_idea_forms, get_idea_form
• Launches: list_launches, get_launch, get_launch_sections, get_launch_section, get_launch_tasks, get_launch_task
• Admin: check_status, health_check, list_users, list_teams

Write tools:

• Roadmaps: manage_bar, manage_lane, manage_milestone
• Bar relationships: manage_bar_connection, manage_bar_link
• OKRs: manage_objective, manage_key_result
• Discovery: manage_idea, manage_opportunity
• Launches: manage_launch, manage_launch_section, manage_launch_task

Example:

{"tool": "list_roadmaps", "arguments": {}}
{"tool": "manage_bar", "arguments": {"action": "create", "roadmap_id": "123", "lane_id": "456", "name": "New feature"}}
{"tool": "manage_idea", "arguments": {"action": "create", "name": "Mobile app improvements"}}

The server uses a clean layered architecture:

┌──────────────────────────────────────────────────────────────┐
│                        cmd/productplan                        │
│                     (entry point, DI)                         │
└──────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  internal/cli │    │  internal/mcp │    │internal/tools │
│  (CLI cmds)   │    │ (JSON-RPC IO) │    │  (handlers)   │
└───────────────┘    └───────────────┘    └───────────────┘
                              │                     │
                              └──────────┬──────────┘
                                         ▼
                              ┌───────────────────┐
                              │   internal/api    │
                              │  (HTTP client)    │
                              └───────────────────┘
                                         │
                                         ▼
                              ┌───────────────────┐
                              │  ProductPlan API  │
                              └───────────────────┘

Key interfaces:

// Tool handler interface (internal/mcp)
type Handler interface {
    Handle(ctx context.Context, args map[string]any) (json.RawMessage, error)
}

// Logger interface (internal/logging)
type Logger interface {
    Debug(msg string, fields ...Field)
    Info(msg string, fields ...Field)
    Warn(msg string, fields ...Field)
    Error(msg string, fields ...Field)
}

Logging format:

{"ts":"2024-12-26T10:30:00Z","level":"info","req_id":"ab12","op":"get_roadmap_bars","dur_ms":245}