miguelarios/productboard-mcp-server

Productboard MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless integration with the Productboard API. This server enables AI assistants and other MCP clients to interact with Productboard through 49 specialized tools covering all major Productboard functionalities.

🚀 Quick Start (Bearer Token - Recommended)

The fastest way to get started with full access to all tools:

# 1. Clone the repository
git clone https://github.com/miguelarios/productboard-mcp-server.git
cd productboard-mcp-server

# 2. Install dependencies
npm install

# 3. Set up environment
cp .env.example .env

# 4. Add your Productboard API key to .env:
PRODUCTBOARD_AUTH_TYPE=bearer
PRODUCTBOARD_API_TOKEN=your_api_key_from_productboard

# 5. Build and run
npm run build
npm start

That's it! Bearer tokens provide immediate access to all 49 tools without complex permission setup.

📍 Get your API key: Visit https://your-subdomain.productboard.com/settings/api-keys in your Productboard workspace.

✨ Key Features

🔐 Simplified Authentication

• 🎯 Bearer Token Fast Path - API keys provide instant access to all tools (recommended)
• 🔧 OAuth2 Support - Role-based scoped access for team collaboration
• 🔄 Automatic Token Management - Handles validation and refresh automatically

🛠️ Complete Tool Coverage

Total: 49 MCP Tools covering 100% of major Productboard functionality:

🎯 Feature Management (6 tools)

• Create, read, update, delete features
• Bulk operations and advanced filtering
• Feature lifecycle management

📦 Product Management (3 tools)

• Product hierarchy navigation
• Component and product creation
• Organizational structure management

📝 Customer Feedback (4 tools)

• Note creation and management
• Feature-feedback linking
• Bulk note operations

👥 User & Company Management (3 tools)

• User directory and profiles
• Company information access
• Workspace member management

🎯 Objectives & Key Results (7 tools)

• OKR creation and tracking
• Feature-objective linking
• Strategic goal management

🚀 Release Management (8 tools)

• Release planning and tracking
• Feature assignment to releases
• Timeline and status management

🔗 Webhooks & Integrations (5 tools)

• Webhook configuration
• Third-party integrations
• Real-time event management

🔍 Search & Analytics (4 tools)

• Global search capabilities
• Advanced filtering and reporting
• Performance metrics and insights

⚡ Bulk Operations (5 tools)

• Mass data operations
• Efficient batch processing
• Time-saving automation

📊 Custom Fields & Export (10 tools)

• Custom field management
• Data export capabilities
• Configuration and setup tools

🏗️ Architecture Highlights

• Bearer Token Fast Path - API keys bypass permission discovery for immediate full access
• OAuth2 Scope System - Granular permissions based on Productboard roles
• Permission-Based Tool Registration - Only relevant tools are loaded
• Comprehensive Error Handling - Robust API interaction with retry logic
• Rate Limiting & Caching - Production-ready performance optimizations

📖 Setup Options

Option 1: Bearer Token (Recommended)

Perfect for personal use or when you need immediate access to all tools:

1. Get your API key from Productboard settings
2. Set PRODUCTBOARD_AUTH_TYPE=bearer in .env
3. Add your PRODUCTBOARD_API_TOKEN
4. Run the server - all 49 tools available instantly!

Option 2: OAuth2 (Team Collaboration)

Ideal for team environments with role-based access:

1. Create OAuth2 application in Productboard
2. Configure scopes based on user roles (contributor/maker/admin)
3. Run OAuth2 setup process
4. Tools are registered based on granted scopes

📚 Detailed Setup Guide: See for comprehensive instructions.

🔧 Configuration

Environment Variables

# Authentication
PRODUCTBOARD_AUTH_TYPE=bearer              # or 'oauth2'
PRODUCTBOARD_API_TOKEN=your_api_key        # For Bearer token auth
PRODUCTBOARD_API_BASE_URL=https://api.productboard.com

# OAuth2 (if using OAuth2)
PRODUCTBOARD_OAUTH_CLIENT_ID=your_client_id
PRODUCTBOARD_OAUTH_CLIENT_SECRET=your_client_secret
PRODUCTBOARD_OAUTH_PRESET=admin            # contributor, maker, admin

# Server Configuration
MCP_SERVER_PORT=3000
LOG_LEVEL=info
CACHE_ENABLED=true

Role-Based Access (OAuth2)

• Contributor (~5 tools): Note creation, user info
• Maker (~15 tools): Notes, users, releases, feedback forms
• Admin (~49 tools): Full system access including OKRs, analytics, integrations

🖥️ MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "productboard": {
      "command": "node",
      "args": ["/full/path/to/productboard-mcp-server/dist/index.js"],
      "env": {
        "PRODUCTBOARD_AUTH_TYPE": "bearer",
        "PRODUCTBOARD_API_TOKEN": "your_api_key_here"
      }
    }
  }
}

🧪 Development

# Development mode
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

📋 Available MCP Tools

🚨 Important Notes

• Bearer tokens provide unrestricted access - Use them for personal/admin scenarios
• OAuth2 provides scoped access - Use for team environments with role restrictions
• All credentials are stored securely - Never commit .env files to version control
• Rate limiting is built-in - Respects Productboard API limits automatically

🛟 Troubleshooting

Common Issues

❌ "Permission denied" errors with Bearer token

• Ensure your API key is valid and from an admin user
• Check that PRODUCTBOARD_AUTH_TYPE=bearer is set correctly

❌ "Tools not loading" with OAuth2

• Verify your OAuth2 scopes match your Productboard role
• Check that authorization was completed successfully
• Review logs for specific permission errors

❌ "Connection failed"

• Verify PRODUCTBOARD_API_BASE_URL is correct
• Check network connectivity to api.productboard.com
• Ensure API key/tokens haven't expired

📄 License

MIT License - see file for details.

🤝 Contributing

This MCP server provides comprehensive Productboard integration with both simple Bearer token authentication and advanced OAuth2 scope-based access control. The Bearer token fast path ensures immediate access to all functionality while OAuth2 enables fine-grained team permissions.

Built with ❤️ using the Model Context Protocol