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

Tool	Description	Input
get_ticket	Fetch ticket with full context	ticket_id
list_tickets	List tickets in a collection	collection_name, status (opt), limit (opt)
update_ticket	Update ticket details	ticket_id, status (opt), description (opt), priority (opt)
add_comment	Add comment to ticket	ticket_id, comment_text

Tier 2: Ticket Discovery

Tool	Description	Input
get_wip_tickets	Find WIP tickets in collection	collection_name
get_sprints	List all sprints/collections	None
find_tickets	Search tickets by text	query, collection_name (opt), status (opt)

Tier 3: Sprint Overview

Tool	Description	Input
get_sprint_status	Get sprint health metrics	collection_name
get_team_workload	See team member assignments	collection_name (opt)

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

Task	Description
build	Build the binary
run	Run the server locally
dev	Run with auto-reload (requires air)
fmt	Format code
lint	Lint code
test	Run tests
tidy	Tidy dependencies
check	Format + lint + test
docker-build	Build Docker image
docker-run	Run standalone Docker container
docker-logs	View Docker logs
docker-stop	Stop Docker container
compose-up	Start with docker-compose
compose-down	Stop docker-compose
compose-logs	View docker-compose logs
clean	Clean build artifacts
setup	Initial setup (copy config template)
install-tools	Install dev tools (air)
health-check	Check if server is running

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.