Brawl Stars MCP

# 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](https://developer.brawlstars.com/)) ### As an NPM Package (Recommended) ```bash npm install -g brawl-stars-mcp ``` ### From Source 1. Clone this repository: ```bash git clone https://github.com/LRxDarkDevil/Brawl-Stars-MCP.git cd Brawl-Stars-MCP ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash 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](https://developer.brawlstars.com/) 2. **Install the MCP server**: ```bash 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: ```json { "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 ```bash # 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](LICENSE) file for details. ## 🙏 Acknowledgments - [Brawl Stars API](https://developer.brawlstars.com/) for providing the game data - [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP standard - The Brawl Stars community for inspiration **Note**: This tool is designed for AI assistants and LLMs.