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

Clone and install dependencies:

git clone <repository-url>
cd plaier
npm install

Build the TypeScript code:
```
npm run build
```

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

🆘 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

Package detail

readme