Brawl Stars MCP

A Model Context Protocol (MCP) server that wraps the Brawl Stars API, providing easy access to game data, player statistics, and club information for AI assistants and LLMs.

🎮 What is this?

This is a Model Context Protocol (MCP) server that allows AI assistants and Large Language Models (LLMs) to access real-time Brawl Stars game data. It's designed to be integrated with AI tools like Claude, GPT-4, or any MCP-compatible AI assistant.

✨ Features

• Player Data: Get player profiles, statistics, and battle logs
• Brawler Information: Access brawler details, stats, star powers, and gadgets
• Club Data: Retrieve club information and member lists
• Battle Logs: Get recent battle history and results
• Game Modes: Access information about different game modes
• Maps: Get map data and rotation information
• Events: Current and upcoming events
• Automatic Tag Cleaning: Handles Brawl Stars player/club tags with proper URL encoding

🚀 Installation

Prerequisites

• Node.js 18.0.0 or higher
• A Brawl Stars API token (get one from Brawl Stars Developer Portal)

As an NPM Package (Recommended)

npm install -g brawl-stars-mcp

From Source

1. Clone this repository:

   git clone https://github.com/LRxDarkDevil/Brawl-Stars-MCP.git
   cd Brawl-Stars-MCP

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

🤖 AI Integration

What is MCP?

Model Context Protocol (MCP) is a standard that allows AI assistants to securely connect to external data sources and tools. This server enables AI assistants to access real-time Brawl Stars data.

Supported AI Platforms

This MCP server works with any AI assistant that supports the Model Context Protocol, including:

• Claude Desktop (Anthropic)
• GPT-4 with MCP plugins
• Custom AI assistants using MCP SDK
• Cursor AI (with MCP support)

Integration Instructions

For Claude Desktop

1. Get your Brawl Stars API token from the Brawl Stars Developer Portal

2. Install the MCP server:

   npm install -g brawl-stars-mcp

3. Configure Claude Desktop:

   • Open Claude Desktop
   • Go to Settings → Model Context Protocol
   • Add a new server with these settings:

     Name: Brawl Stars
     Command: npx
     Arguments: brawl-stars-mcp --token YOUR_API_TOKEN_HERE
     

4. Restart Claude Desktop and start asking about Brawl Stars!

For Other AI Assistants

Add this configuration to your MCP config file:

{
  "mcpServers": {
    "brawlstars": {
      "command": "npx",
      "args": ["brawl-stars-mcp", "--token", "YOUR_API_TOKEN_HERE"]
    }
  }
}

Example AI Conversations

Once integrated, you can ask your AI assistant questions like:

• "Get player information for #98VC8YUR"
• "Show me the battle log for player #2Y0J0Q0"
• "What are the stats for Shelly brawler?"
• "Get information about club #CCY9CGPQ"
• "Show me all available brawlers"
• "What events are currently running?"

📚 API Reference

The MCP provides the following functions:

Function	Description	Parameters
get_player	Get player information by tag	tag (string)
get_player_battlelog	Get player's recent battles	tag (string)
get_brawler	Get brawler information by ID	id (number)
get_brawlers	Get all available brawlers	None
get_club	Get club information by tag	tag (string)
get_club_members	Get club member list	tag (string)
get_events	Get current and upcoming events	None
get_maps	Get available maps	None
get_game_modes	Get game modes information	None

🔧 Development

Building from Source

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Test the build
npm start -- --token YOUR_API_TOKEN_HERE

Project Structure

src/
├── api/
│   └── brawlstars-api.ts    # Main API wrapper
├── types/
│   ├── index.ts             # Type definitions
│   └── schemas.ts           # Zod schemas for validation
├── utils/
│   └── helpers.ts           # Utility functions
└── index.ts                 # MCP server entry point

Contributing

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

🛠️ Troubleshooting

Common Issues

"Resource not found" error:

• Make sure the player/club tag is correct
• Verify your API token is valid
• Check if the player/club still exists

"API token is required" error:

• Ensure you're passing the --token argument
• Verify your API token from the Brawl Stars Developer Portal

MCP connection issues:

• Restart your AI assistant after adding the MCP server
• Check that the command and arguments are correct
• Ensure Node.js is installed and accessible

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Brawl Stars API for providing the game data
• Model Context Protocol for the MCP standard
• The Brawl Stars community for inspiration

Note: This tool is designed for AI assistants and LLMs.