mcp-bonusly

Comprehensive MCP server for Bonusly employee recognition platform

MCP server to interact with Bonusly API, enabling management of employee recognition bonuses through Claude and other MCP clients.

🚀 Available on Smithery for easy local installation!

Table of Contents

• Quick Start
• Features
• Installation
• Setup
• Available Tools
• Example Prompts
• Development
• License

Quick Start

Quick Installation

git clone https://github.com/ajramos/mcp-bonusly
cd mcp-bonusly
uv sync

Quick Setup

1. Get your Bonusly API token from https://bonus.ly/api
2. Create a .env file with your token:

   BONUSLY_API_TOKEN=your_api_token_here
   

3. Configure Claude Desktop to use the server

Features

✨ Complete Bonus Management

• List bonuses with advanced filtering (including new user_email parameter for team analysis)
• Create new bonuses with validation
• Retrieve bonus details for specific bonuses

🔍 Advanced Filtering

• Filter by date range
• Filter by giver email
• Filter by receiver email
• Filter by hashtags
• Limit number of results

🛡️ Security

• Secure authentication with API token
• Input data validation
• Robust error handling

Installation

Option 1: Install from Smithery (Recommended)

This MCP is available on Smithery as a local installation:

1. Visit Smithery
2. Search for "mcp-bonusly"
3. Follow the installation instructions for local MCPs
4. Configure your Bonusly API token (see Setup section below)

Option 2: Manual Installation with uv

git clone https://github.com/ajramos/mcp-bonusly
cd mcp-bonusly
uv sync

Option 3: Manual Installation with pip

git clone https://github.com/ajramos/mcp-bonusly
cd mcp-bonusly
pip install -e .

Setup

1. Get Bonusly API Token

1. Go to https://bonus.ly/api
2. Sign in to your Bonusly account
3. Create a new API token
4. Copy the generated token

2. Configure Environment Variables

Create a .env file in the project root directory:

BONUSLY_API_TOKEN=your_api_token_here

3. Configure Claude Desktop

Add this configuration to your Claude Desktop configuration file:

{
  "mcpServers": {
    "mcp-bonusly": {
      "command": "uv",
      "args": [
        "--directory", 
        "/full/path/to/mcp-bonusly",
        "run",
        "mcp-bonusly"
      ],
      "env": {
        "BONUSLY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Available Tools

🎁 list_bonuses

List bonuses with optional filters.

Parameters:

• limit (optional): Number of bonuses to return (1-100, default: 20)
• start_date (optional): Start date (format: YYYY-MM-DD)
• end_date (optional): End date (format: YYYY-MM-DD)
• giver_email (optional): Giver's email address
• receiver_email (optional): Receiver's email address
• user_email (optional): User's email address (bonuses given or received by this user). Recommended for team analysis: search for each team member individually to ensure complete coverage.
• hashtag (optional): Hashtag to filter by (e.g., #teamwork)
• include_children (optional): Include bonus replies

🆕 create_bonus

Create a new recognition bonus.

Parameters:

• giver_email (optional): Giver's email address (admin only, regular users send bonuses in their own name)
• reason (required): Bonus reason (e.g., "+10 @user for #teamwork")
• parent_bonus_id (optional): Parent bonus ID for replies

🔍 get_bonus

Get details of a specific bonus.

Parameters:

• bonus_id (required): ID of the bonus to retrieve

Example Prompts

List Recent Bonuses

"Show me the last 10 bonuses given"

Create a Bonus

"Create a 5-point bonus for john@company.com for excellent work on the project with #teamwork"

Search Bonuses by Hashtag

"Show me all bonuses with hashtag #innovation from last month"

Get Bonus Details

"Get details for bonus with ID 24abcdef1234567890abcdef"

Development

Setup Development Environment

git clone https://github.com/ajramos/mcp-bonusly
cd mcp-bonusly
uv sync
uv run mcp-bonusly

Debugging with MCP Inspector

For the best debugging experience, we recommend using the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-bonusly run mcp-bonusly

View Server Logs

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-bonusly.log

# Linux 
tail -n 20 -f ~/.config/Claude/logs/mcp-server-mcp-bonusly.log

# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp-server-mcp-bonusly.log" -Wait -Tail 20

Project Structure

mcp-bonusly/
├── src/
│   └── mcp_bonusly/
│       ├── __init__.py
│       ├── server.py          # Main MCP server
│       ├── client.py          # Bonusly API client
│       ├── models.py          # Pydantic models
│       └── exceptions.py      # Custom exceptions
├── tests/                     # Tests (coming soon)
├── .env.example              # Environment variables example
├── .gitignore
├── README.md
├── pyproject.toml
└── LICENSE

Security

• All credentials are handled through environment variables
• API token is stored securely
• No data is sent to third parties except Bonusly API
• Input validation on all operations

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

If you encounter any issues:

1. Check the logs using the debugging instructions above
2. Verify your API token in the .env file
3. Open an issue with:
   • Your operating system
   • Python version
   • Error messages or logs
   • Steps to reproduce the issue

About Bonusly

Bonusly is an employee recognition platform that enables companies to create a culture of appreciation and engagement. Employees can give points to each other with personalized messages and hashtags that reflect company values.

---

Created with ❤️ by Angel Ramos