Plaier MCP Server

A powerful Model Context Protocol (MCP) server that provides access to the Plaier Football API, offering comprehensive football analytics, predictions, and insights directly within your AI conversations.

🚀 Features

🏟️ Team Analytics

• Team Search & Details: Find teams by name with fuzzy search, get detailed information including scores and market values
• Tournament Analysis: View all teams in specific tournaments with rankings
• Performance Metrics: Access team scores, effective ratings, and performance analysis in tournaments
• Team Improvement: Get suggestions for improving teams by position with expected goal difference impact
• Important Players: Analyze the most critical players for team performance

⚽ Player Intelligence

• Advanced Search: Find players by name with optional team context
• Player Rankings: Comprehensive ranking system with filters for age, nationality, position, tournaments
• Team Rosters: Complete player lists for teams and tournaments
• Market Valuations: Player fair market values and scoring metrics
• Position & Nationality Data: Access to all positions and nationalities for filtering

🎯 Match Predictions & Analytics

• Match Predictions: AI-powered outcome predictions with probabilities and fair betting odds
• Exact Result Predictions: Specific scoreline predictions with probabilities
• Lineup Optimization: Get the best 1000 lineup combinations for any matchup
• Formation Analysis: Analyze optimal formations with expected goal differences
• Player Impact: See how often players appear in optimal lineups
• Match Simulation: Run detailed match simulations with events and statistics
• Team Schedules: View past and upcoming fixtures for any team

🏆 Tournament Intelligence

• Tournament Data: Access 85+ national tournaments plus UEFA/CONMEBOL championships
• Tournament Search: Find tournaments by name with fuzzy search
• Fixtures & Results: Complete match schedules and results
• Season Predictions: End-of-season table predictions with points and goal differences
• Position Probabilities: Detailed probability matrices for final standings

💰 Transfer Market Analysis

• Transfer Impact: Analyze how players would affect specific teams or entire tournaments

📦 Installation

Prerequisites

• Node.js 18+
• npm or yarn
• Plaier API access credentials

Setup

1. Clone and install dependencies:

git clone <repository-url>
cd plaier
npm install

2. Build the TypeScript code:

npm run build

3. Set up environment variables:

export PLAIER_AUTH_TOKEN="your_plaier_api_token"

Or create a .env file:

echo "PLAIER_AUTH_TOKEN=your_plaier_api_token" > .env

🔧 Configuration

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | PLAIER_AUTH_TOKEN | Your Plaier API authentication token | ✅ Yes |

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "plaier": {
      "command": "npx",
      "args": ["-y", "plaier-mcp-server@latest"],
      "env": {
        "PLAIER_AUTH_TOKEN": "your_api_token_here"
      }
    }
  }
}

🛠️ Available Tools

Team Tools (7 tools)

• search_teams - Find teams by name with fuzzy search, with optional detailed output
• get_team_details - Get detailed information about a specific team
• get_teams_by_tournament - List all teams in a tournament with rankings
• get_team_performance_in_tournament - Analyze team performance in tournaments with various metrics
• get_team_improvement - Get suggestions for improving a team by position
• get_team_most_important_players - Analyze the most important players for a team
• get_all_teams - Get all teams with optional national team filtering

Player Tools (5 tools)

• search_players - Find players by name with optional team context and detailed output
• get_player_details - Get comprehensive player information including stats and market value
• rank_players - Advanced player rankings with extensive filtering (tournaments, teams, age, nationality, position)
• get_team_players - Get all players from a specific team with position distribution
• get_tournament_players - Get players from a tournament with top player analysis

Match Tools (6 tools)

• predict_match - Predict match outcomes with probabilities and fair betting odds
• get_best_lineups - Get up to 1000 optimal lineup combinations for matchups
• get_best_formations - Analyze best formations with expected goal differences
• get_lineup_count - See how often players appear in optimal lineups (player importance analysis)
• get_team_schedule - Get team's match schedule (past and upcoming fixtures)
• simulate_match - Run detailed match simulations with events and statistics

Tournament Tools (5 tools)

• get_tournaments - List all available tournaments with market values and country filtering
• search_tournaments - Find tournaments by name using fuzzy search
• get_tournament_fixtures - Get match schedules and results with filtering options
• predict_tournament - End-of-season table predictions with points and goal differences
• get_tournament_probabilities - Position probability matrices for final standings

Transfer Tools (1 tool)

• get_transfer_impact - Analyze transfer impact on specific teams or entire tournaments

Position Tools (2 tools)

• get_positions - Get all player positions with IDs and position groups
• get_position_groups - Get position groups with contained positions

Nationality Tools (1 tool)

• get_nationalities - Get all nationalities with IDs for player filtering

💡 Usage Examples

Basic Team Analysis

"Find information about Manchester City"
→ Uses search_teams and get_team_details

"Show me all teams in the Premier League"
→ Uses get_teams_by_tournament

"How can Real Madrid improve their squad?"
→ Uses get_team_improvement

"Who are the most important players for Barcelona?"
→ Uses get_team_most_important_players

Player Research

"Who are the top 10 players in Serie A?"
→ Uses rank_players with tournament filter

"Find Lionel Messi's current stats"
→ Uses search_players and get_player_details

"Show me all Brazilian midfielders under 25"
→ Uses rank_players with nationality and position filters

"Get all positions available in the database"
→ Uses get_positions

Match Predictions & Analysis

"Predict the outcome of Barcelona vs Real Madrid"
→ Uses predict_match (returns probabilities and expected score)

"Get exact scoreline predictions for Liverpool vs Arsenal"
→ Uses predict_match with exact-result-prediction type

"What's the best lineup for Bayern Munich against Liverpool?"
→ Uses get_best_lineups (up to 1000 optimal combinations)

"Analyze the best formations for Manchester City vs Chelsea"
→ Uses get_best_formations

"Simulate a match between Arsenal and Chelsea"
→ Uses simulate_match (detailed events and statistics)

"Which players appear most in Manchester City's best lineups?"
→ Uses get_lineup_count

"Show me PSG's upcoming fixtures"
→ Uses get_team_schedule

Tournament Analysis

"Show me the current Bundesliga table prediction"
→ Uses predict_tournament

"What are the upcoming Champions League fixtures?"
→ Uses get_tournament_fixtures

"Find the Premier League tournament ID"
→ Uses search_tournaments

"What's the probability matrix for La Liga final standings?"
→ Uses get_tournament_probabilities

Transfer Analysis

"How would Haaland impact different teams if he transferred?"
→ Uses get_transfer_impact

"Analyze Mbappé's potential impact on all Serie A teams"
→ Uses get_transfer_impact with tournament_id

🏗️ Development

Project Structure

plaier/
├── src/
│   ├── api/
│   │   ├── client.ts            # API client with authentication
│   │   └── types.ts             # TypeScript interfaces
│   ├── tools/
│   │   ├── team-tools.ts        # Team-related MCP tools (7 tools)
│   │   ├── player-tools.ts      # Player-related MCP tools (5 tools)
│   │   ├── match-tools.ts       # Match prediction and analysis tools (6 tools)
│   │   ├── tournament-tools.ts  # Tournament analysis tools (5 tools)
│   │   ├── transfer-tools.ts    # Transfer market analysis tools (1 tool)
│   │   ├── position-tools.ts    # Position and position group tools (2 tools)
│   │   └── nationality-tools.ts # Nationality reference tools (1 tool)
│   ├── utils/
│   │   ├── validation.ts        # Input validation with Zod schemas
│   │   └── formatting.ts        # Response formatting utilities
│   ├── config.ts                # Configuration management
│   └── index.ts                 # Main MCP server entry point
├── package.json
├── tsconfig.json
└── README.md

Tool Summary

Total Tools Available: 27

• Team Tools: 7
• Player Tools: 5
• Match Tools: 6
• Tournament Tools: 5
• Transfer Tools: 1
• Position Tools: 2
• Nationality Tools: 1

🔍 Troubleshooting

Common Issues

Authentication Errors

Error: PLAIER_AUTH_TOKEN environment variable is required

• Ensure your API token is set in the environment
• Verify the token has the correct permissions

API Rate Limits

Error: Rate limit exceeded: Too many requests

• The Plaier API has rate limits - reduce request frequency
• Consider implementing request queuing for high-volume usage

No Data Found

No teams found matching "..."

• Check spelling and try partial matches
• Use broader search terms
• Verify the entity exists in the API

Tool Execution Failures

• Check that all required parameters are provided
• Verify parameter types match the schema
• Review the tool's input requirements

Debug Mode

Start the server with debugging enabled:

npm run inspect

Then connect a debugger to localhost:9229.

📊 Data Coverage

Tournaments

• 85+ National Club Tournaments: Premier League, La Liga, Bundesliga, Serie A, Ligue 1, and more
• International Competitions: UEFA Euro, CONMEBOL Copa América
• Multiple Levels: From top-tier leagues to lower divisions

Data Levels

• Level 2 Data: 12 major tournaments with advanced analytics
• Level 3 Data: Injury/suspension tracking, detailed player availability
• Level 4 Data: Youth leagues and lower divisions

Update Frequency

• Daily: Match results, fixtures, player availability
• Weekly: Player scores, team ratings, market valuations

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Style

• Use TypeScript with strict mode
• Follow the existing code structure
• Add proper error handling
• Include JSDoc comments for public methods
• Validate inputs with Zod schemas

📝 License

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

🔗 Links

• Plaier API Documentation
• Model Context Protocol
• MCP TypeScript SDK

🆘 Support

For questions about:

• MCP Server: Open an issue in this repository
• Plaier API: Contact Plaier support
• MCP Protocol: Check the MCP documentation

Built with ⚽ for football analytics enthusiasts