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

Related MCP server: Insperity MCP Server

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