Favro MCP Server

A Model Context Protocol (MCP) server that wraps the Favro API, enabling AI and other MCP clients to programmatically interact with Favro tickets and sprints.

Features

• 9 Core Tools across 3 tiers:

  • Ticket Completion: Get ticket details, list tickets, update tickets, add comments
  • Ticket Discovery: Find WIP tickets, list sprints, search tickets
  • Sprint Overview: Get sprint status, view team workload

• HTTP Transport: Accessible from Claude Code, browser plugins, and other MCP clients

• Configuration: YAML-based config with environment variable overrides

• Docker Support: Multi-stage Docker build (20.3MB) with docker-compose

• Go Best Practices: Follows standard project layout with cmd/ and internal/ directories

Quick Start

Prerequisites

• Go 1.25 or Docker

1. Configuration

Copy the example config:

cp favro-config.example.yaml favro-config.yaml

Edit favro-config.yaml with your Favro details:

favro:
  api_email: "your-email@company.com"
  api_token: "your-api-token"
  organization_id: "your-org-id"
  server_port: 3000
  collections:
    - name: "Sprint 1"
      id: "collection-id-1"
    - name: "Backlog"
      id: "collection-id-backlog"

Finding your Favro details:

• api_email: Your Favro account email
• api_token: Get from Favro Settings → API Tokens
• organization_id: Get from Favro Settings → Organization ID
• collection_ids: From each collection's URL or API response

2. Build & Run

Locally:

go build -o favro-mcp ./cmd
./favro-mcp -config favro-config.yaml

With Docker:

docker-compose up -d

The server will start on http://localhost:3000/mcp

Tools

Tier 1: Ticket Completion

Tier 2: Ticket Discovery

Tier 3: Sprint Overview

Configuration Options

Environment Variables (Override config file)

export FAVRO_API_EMAIL="your-email@company.com"
export FAVRO_API_TOKEN="your-api-token"
export FAVRO_ORGANIZATION_ID="your-org-id"
export FAVRO_SERVER_PORT="3000"

Config File (favro-config.yaml)

favro:
  api_email: "your-email@company.com"
  api_token: "your-api-token"
  organization_id: "your-org-id"
  server_port: 3000
  collections:
    - name: "Sprint 1"
      id: "collection-id"
    - name: "Sprint 2"
      id: "collection-id"

Priority: Environment variables > Config file

Development

Build

go build -o favro-mcp ./cmd

Run

go run ./cmd -config favro-config.yaml

Format Code

go fmt ./...

Lint

go vet ./...

Update Dependencies

go mod tidy

Using Mise for Tasks

This project includes a mise.toml file with common commands. Install mise and run:

# List all available tasks
mise tasks

# Run a task
mise run build
mise run fmt
mise run lint
mise run test
mise run docker-build
mise run compose-up

Available Tasks

Docker

Build Image

docker build -t favro-mcp .

Run with Docker Compose

docker-compose up -d

View Logs

docker-compose logs -f favro-mcp

Stop Container

docker-compose down

Run Standalone

docker run -d \
  --name favro-mcp \
  -p 3000:3000 \
  -v $(pwd)/favro-config.yaml:/config/favro-config.yaml:ro \
  favro-mcp

Project Structure

favro-mcp/
├── cmd/
│   └── main.go                    # Server entry point
├── internal/
│   ├── config/                    # Configuration loading
│   ├── client/                    # Favro API client
│   └── handlers/                  # MCP tool implementations
├── Dockerfile                     # Multi-stage Docker build
├── docker-compose.yml             # Docker Compose config
├── favro-config.example.yaml      # Configuration template
├── CLAUDE.md                      # Developer guide
└── README.md                      # This file

Architecture

HTTP Transport

• Server uses StreamableHTTPHandler from MCP Go SDK
• Accessible on http://localhost:{port}/mcp
• Supports multiple concurrent connections

Authentication

• Favro API uses Basic Auth (email:token)
• All requests include organizationId header
• Credentials configured via favro-config.yaml or environment variables

Tool Pattern

Each MCP tool:

1. Takes typed input with JSON schema annotations
2. Calls Favro API via internal client
3. Returns structured output and human-readable text
4. Includes error handling with LLM-friendly messages

Rate Limits

Favro API rate limits:

• Standard: 50 requests/hour
• Enterprise: Up to 10,000 requests/hour

Integration with Claude Code

1. Start the server:

   ./favro-mcp -config favro-config.yaml
   

2. Configure Claude Code to use MCP at http://localhost:3000/mcp

3. Call tools with collection names from your config:

   Tool: list_tickets
   Input: {"collection_name": "Sprint 1", "limit": 10}
   

Future Roadmap

• Browser Plugin - Native messaging for browser integration
• Kubernetes Support - Helm charts for cloud deployment
• Caching Layer - Redis for performance optimization
• Advanced Search - Elasticsearch integration
• WebSocket Transport - Real-time updates
• Monitoring - Prometheus metrics, structured logging

Troubleshooting

"Failed to load configuration"

• Ensure favro-config.yaml exists and is valid YAML
• Check that all required fields are present
• Verify environment variables if using those

"Favro API error"

• Verify API credentials are correct
• Check organization ID matches your Favro account
• Ensure collection IDs are valid and accessible
• Check API rate limits haven't been exceeded

"Cannot connect to localhost:3000"

• Verify the server started successfully (check logs)
• Ensure port 3000 is not in use: lsof -i :3000
• Try a different port: ./favro-mcp -config favro-config.yaml with server_port: 3001

Docker Build Issues

• Ensure Docker daemon is running
• Check disk space: docker system prune to clean up
• Try rebuilding without cache: docker build --no-cache -t favro-mcp .

Support

For issues or questions:

1. Check CLAUDE.md for developer documentation
2. Review Favro API docs at https://favro.com/developer
3. Check logs for error details
4. Open an issue with detailed error messages

License

This project wraps the Favro API. Ensure you comply with Favro's terms of service when using this tool.