Bonusly

Available on Smithery

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 [email protected] 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