The Sleeper MCP Server connects Claude Desktop to the Sleeper Fantasy Football API, enabling natural language queries for comprehensive league, player, and matchup analysis. Key capabilities:
NFL State: Retrieve the current NFL season, week, and season type (preseason, regular, postseason, or offseason).
League Management: Find all leagues for a given Sleeper username (with optional season filtering), fetch league settings, rosters (with draft position metadata), users, and roster-to-user mappings.
Draft Analysis: Access complete draft history including pick positions, keeper indicators (🔒), and original draft team.
Player Information: Search players by name and position (QB, RB, WR, TE, K, DEF), view trending players (most added/dropped), and get detailed stats for a full season or specific week.
Matchups: Retrieve scheduled matchups and real-time scores for any week in a league.
Performance: Intelligent TTL-based caching and rate limiting with exponential backoff ensure efficient and reliable API usage.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Sleeper MCP Server what are this week's matchups in my league 123456789?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides Claude Desktop with access to Sleeper Fantasy Football API data. This server enables users to query league information, player data, matchups, and draft results through natural language interactions with Claude.
League Management: Query leagues, rosters, users, and league settings
Draft Analysis: Complete draft results with pick positions, keeper status, and team attribution
Full draft history with all rounds and picks
Player draft metadata showing original draft position and team
Keeper identification with 🔒 indicators
Free agent tracking for undrafted players
Player Information: Search players, get statistics, and trending data
Matchup Analysis: View current and historical matchups with real-time scoring
Intelligent Caching: Optimized API usage with TTL-based caching
Rate Limiting: Respects Sleeper API limits with exponential backoff
Related MCP server: Sleeper Fantasy MCP
Python 3.10 or higher
Claude Desktop application
Clone the repository:
git clone <repository-url>
cd sleeper-mcp-serverInstall the package:
pip install -e .For development with testing and linting tools:
pip install -e ".[dev]"Add the following configuration to your Claude Desktop MCP settings file:
Location of config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Basic Configuration:
{
"mcpServers": {
"sleeper": {
"command": "python",
"args": ["-m", "sleeper_mcp_server"],
"disabled": false,
"autoApprove": [
"get_user_leagues",
"get_league_info",
"search_players",
"get_trending_players",
"get_nfl_state"
]
}
}
}Auto-approving every tool:
{
"mcpServers": {
"sleeper": {
"command": "python",
"args": ["-m", "sleeper_mcp_server"],
"disabled": false,
"autoApprove": [
"get_user_leagues",
"get_league_info",
"get_league_rosters",
"get_league_rosters_with_draft_info",
"get_league_users",
"get_roster_user_mapping",
"get_league_draft",
"search_players",
"get_trending_players",
"get_player_stats",
"get_matchups",
"get_matchup_scores",
"get_nfl_state"
]
}
}
}get_user_leaguesGet all leagues for a username in a specific season.
Parameters:
username (required): Sleeper username to look up
season (optional): Season year (defaults to current season)
Example Usage:
Show me all leagues for username "john_doe"
Show me all leagues for username "john_doe" in 2025get_league_infoGet detailed information about a specific league.
Parameters:
league_id (required): League ID to retrieve information for
Example Usage:
Get information for league ID "123456789"get_league_rostersGet all team rosters in a league.
Parameters:
league_id (required): League ID to retrieve rosters for
Example Usage:
Show me all rosters in league "123456789"get_league_usersGet all users/participants in a league.
Parameters:
league_id (required): League ID to retrieve users for
Example Usage:
Who are the users in league "123456789"?get_league_rosters_with_draft_infoGet all team rosters in a league with complete draft position metadata for each player.
Parameters:
league_id (required): League ID to retrieve rosters for
Example Usage:
Show me all rosters with draft information for league "123456789"get_roster_user_mappingGet a clear mapping of roster IDs to user names for a league.
Parameters:
league_id (required): League ID to get roster-user mapping for
Example Usage:
Show me the roster to user mapping for league "123456789"get_league_draftGet complete draft results and pick information for a league.
Parameters:
league_id (required): League ID to get draft information for
Example Usage:
Show me the draft results for league "123456789"search_playersSearch for players by name with optional position filtering.
Parameters:
query (required): Player name or partial name to search for
position (optional): Position filter (QB, RB, WR, TE, K, DEF)
Example Usage:
Search for players named "Josh Allen"
Find all quarterbacks with "Josh" in their nameget_trending_playersGet trending players (most added/dropped).
Parameters:
sport (optional): Sport type (default: "nfl")
add_drop (optional): Type of trend - "add" or "drop" (default: "add")
Example Usage:
Show me the most added players this week
What players are being dropped the most?get_player_statsGet player statistics for a specific season and optional week.
Parameters:
player_id (required): Player ID to get stats for
season (optional): Season year (defaults to current season)
week (optional): Week number within the season
Example Usage:
Get stats for player ID "4046"
Get stats for player ID "4046" in week 5get_matchupsGet matchups for a specific week in a league.
Parameters:
league_id (required): League ID to retrieve matchups for
week (required): Week number (1-22)
Example Usage:
Show me week 5 matchups for league "123456789"get_matchup_scoresGet real-time scoring information for matchups in a specific week.
Parameters:
league_id (required): League ID to retrieve scores for
week (required): Week number (1-22)
Example Usage:
What are the current scores for week 8 in league "123456789"?get_nfl_stateGet the current NFL state including season, week, and season type.
Parameters:
None
Example Usage:
What's the current NFL week?
What season are we in?The server implements intelligent rate limiting to respect Sleeper API guidelines:
Rate Limit: Follows Sleeper's documented rate limits
Retry Logic: Exponential backoff (1s, 2s, 4s, 8s) for rate-limited requests
Queue Management: Requests are queued during rate limit periods
User Feedback: Clear messages when rate limits are encountered
Different data types have optimized cache TTL values:
Data Type | Cache TTL | Reason |
Player Data | 1 hour | Relatively static during season |
League Settings | 24 hours | Rarely change mid-season |
Draft Data | 24 hours | Historical data, doesn't change |
Matchup Data (active) | 5 minutes | Real-time scoring updates |
Matchup Data (completed) | 1 hour | Historical data is stable |
Trending Players | 30 minutes | Updated frequently |
Roster Data | 15 minutes | Changes with transactions |
Roster Data (with draft) | 15 minutes | Changes with transactions |
Cache Features:
In-memory caching for optimal performance
TTL-based expiration
Automatic cache invalidation
Cache hit/miss logging for monitoring
# Get your leagues
"Show me all leagues for username 'myusername'"
# Get league details
"What are the settings for league ID '123456789'?"
# View rosters
"Show me all the rosters in my main league"
# View rosters with draft information
"Show me all rosters with draft info - I want to see where each player was drafted and by whom"# Search for players
"Find all players named 'Cooper'"
# Get trending players
"What players are being added the most this week?"
# Player statistics
"Show me Josh Allen's stats"
"Show me Josh Allen's stats for week 5"# Current week matchups
"What are this week's matchups in my league?"
# Live scoring
"What are the current scores for week 8?"
# Historical data
"Show me the results from week 3"# Complete draft results
"Show me the draft results for my league"
# Roster with draft info
"Show me all rosters with draft information - I want to see where each player was drafted"
# Keeper analysis
"Which players were kept from last year and what was their original draft cost?"
# Draft value analysis
"Show me players who are outperforming their draft position"Symptoms:
Claude Desktop shows "Server unavailable" error
No response from MCP tools
Solutions:
Verify Python installation: python --version (should be 3.10+)
Check package installation: pip show sleeper-mcp-server
Verify Claude Desktop configuration syntax
Check logs for specific error messages
Symptoms:
"API request failed" errors
"Invalid league ID" messages
Solutions:
Verify league IDs are correct (18-character strings)
Check username spelling and case sensitivity
Ensure Sleeper API is accessible from your network
Try again after a few minutes (may be temporary API issues)
Symptoms:
"Rate limit exceeded" messages
Slow response times
"Please wait" messages
Solutions:
Wait for the specified retry period
Reduce frequency of requests
Use cached data when possible
Check if multiple instances are running
Symptoms:
Stale data being returned
Inconsistent results
Solutions:
Restart the MCP server to clear cache
Adjust the TTL constants in sleeper_mcp_server/cache.py
Check system memory availability
Symptoms:
Tools not appearing in Claude Desktop
Solutions:
Validate JSON syntax in Claude Desktop config
Restart Claude Desktop after configuration changes
Check file permissions on config file
The server logs to stderr at INFO. The level is set in sleeper_mcp_server/__main__.py;
there is no environment-variable override.
Check Logs: Read the server's stderr output for detailed error information
Verify Configuration: Ensure Claude Desktop MCP configuration is correct
Test API Access: Verify you can access Sleeper API directly
Update Dependencies: Ensure all packages are up to date
Restart Services: Try restarting both the MCP server and Claude Desktop
Use position filtering in player searches
Cache frequently accessed league data
Limit historical matchup queries
Batch similar requests when possible
Use appropriate cache TTL settings
Monitor rate limit usage
# Run all tests
pytest
# Run with coverage
pytest --cov=sleeper_mcp_server
# Run specific test file
pytest tests/test_server.py# Format code
black sleeper_mcp_server/
# Sort imports
isort sleeper_mcp_server/
# Lint code
flake8 sleeper_mcp_server/
# Type checking
mypy sleeper_mcp_server/Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
Sleeper API for providing comprehensive fantasy football data including detailed draft information
Model Context Protocol for the MCP framework
Claude Desktop for MCP integration
For issues and questions:
Check the troubleshooting section above
Review existing GitHub issues
Create a new issue with detailed information about your problem
Note: This MCP server is not officially affiliated with Sleeper. It's a third-party integration that uses Sleeper's public API.
Get draft results and pick information for a league.
| Name | Required | Description | Default |
|---|---|---|---|
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description's 'Get' is consistent. The description adds no further behavioral context (e.g., pagination, data freshness), but the annotations cover the essential safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is appropriately front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set (1 required string), annotations, and presence of an output schema, the description provides sufficient context for most use cases. It lacks details on output structure, but the output schema presumably covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The tool description mentions 'for a league' but does not explain league_id format, source, or how to obtain it beyond what the schema already shows (type string, required). This adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'draft results and pick information for a league', providing a specific verb and resource. It distinguishes itself from sibling tools like get_league_info or get_league_rosters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (to get draft results), but does not mention when not to use it or suggest alternative tools like get_league_rosters_with_draft_info. However, context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific league.
| Name | Required | Description | Default |
|---|---|---|---|
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description does not contradict and adds no additional behavioral context. The description does not disclose any extra traits beyond the annotations, but it also does not mislead. Given the annotations cover the safety and data volatility profile, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded. Every word adds value; no irrelevant information is present. It is optimally concise for a straightforward retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 1 parameter, an output schema (assumed present), and annotations, the description is minimally adequate. It tells the agent what the tool does but not what the returned data looks like or any usage caveats. The output schema may cover return structure, but the description could be enriched with a brief note on the scope of 'detailed information' (e.g., includes settings, member count).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides minimal additional meaning beyond the schema. It only mentions 'a specific league' as the target, which weakly implies the league_id parameter identifies the league. No details on format, source, or constraints are given, leaving the agent with little to infer about how to provide the parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get detailed information about a specific league' clearly states the verb (get), resource (league), and specificity (specific league). It effectively distinguishes from sibling tools like get_nfl_state or get_user_leagues, which target different data. The purpose is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is used when details about a particular league are needed, but it provides no explicit guidance on when to use it versus alternatives like get_league_rosters or get_league_users. No exclusions or contextual cues are given, leaving some ambiguity for complex decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all team rosters in a league.
| Name | Required | Description | Default |
|---|---|---|---|
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true. The description ('Get all team rosters') aligns with these, but adds no additional behavioral details (e.g., authentication, ordering, or performance implications). It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded with the key action. Every word is meaningful, though room exists to add a brief usage hint without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 required parameter), the presence of an output schema (not shown), and annotations covering safety and scope, the description is nearly complete. A bit more context on the return format or edge cases would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain what a 'league_id' is or how to obtain it. Since there is only one parameter, the description should provide context, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('team rosters'), and the scope ('in a league'). It distinguishes from the sibling tool 'get_league_rosters_with_draft_info' by omission, though it does not explicitly call out the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings (e.g., when draft info is needed or not). The description lacks context for an agent to make a selection decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all rosters with draft-position metadata per player.
| Name | Required | Description | Default |
|---|---|---|---|
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds no further behavioral context (e.g., no mention of data freshness, pagination, or that it combines two endpoints). The description is consistent but adds minimal value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. It is front-loaded and has no wasted words. However, it could include a brief note about combining roster and draft data without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, explanation of return values is not needed. However, the tool combines two data sources (rosters and draft info), and the description does not mention this aggregation. It is minimally complete but lacks context about its composite nature relative to siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate by explaining the league_id parameter. It does not add any meaning beyond the schema's type and name. The agent must infer that league_id identifies the league, which is trivial but still a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all rosters with draft-position metadata per player, using a specific verb and resource. It distinguishes from siblings like 'get_league_rosters' (just rosters) and 'get_league_draft' (draft info alone), making its unique value obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when both roster and draft metadata are needed) but offers no explicit guidance on when to avoid it or which sibling alternative to choose (e.g., 'get_league_rosters' if only rosters are needed). No exclusions or context conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all users/participants in a league.
| Name | Required | Description | Default |
|---|---|---|---|
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint, so the description adds little beyond confirming the tool returns 'all users/participants'. No contradictions, but no additional behavioral details (e.g., ordering, pagination).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence), which makes it concise, but lacks structure such as separating purpose from usage notes. It earns its place but could be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool is simple with one parameter, the description is minimally adequate. However, it misses opportunities to differentiate from sibling tools or provide parameter context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the tool description does not clarify the required league_id parameter (e.g., format or source). The agent must infer meaning solely from the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'all users/participants in a league', but does not explicitly differentiate from sibling tools like get_league_rosters, which serves a different purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives (e.g., get_league_info or get_league_rosters). The agent receives no context about selection criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get matchups for a specific week in a league.
| Name | Required | Description | Default |
|---|---|---|---|
| week | Yes | ||
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description is consistent with annotations (readOnlyHint, openWorldHint). No additional behavioral traits disclosed beyond annotations, but no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and front-loaded. No unnecessary words, but lacks depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters and existence of output schema, description is minimally adequate. Could provide more context on output structure or usage notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions). Description adds minimal meaning beyond mentioning 'specific week' and 'league', not explaining parameters individually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'get' and resource 'matchups' with context (week, league). However, it does not distinguish from sibling tool 'get_matchup_scores', which likely provides similar or more detailed data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_matchup_scores. No explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get real-time scoring for matchups in a specific week.
| Name | Required | Description | Default |
|---|---|---|---|
| week | Yes | ||
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds 'real-time', which is a helpful behavioral trait beyond the annotations. No contradictions. However, it does not detail any other behaviors like caching or latency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no superfluous words. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While output schema exists and reduces the need to describe return values, the description lacks parameter details and does not differentiate from sibling tools like get_matchups. For a tool with two required parameters, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does not explain either parameter (league_id or week) beyond the context 'specific week', leaving significant ambiguity about format, constraints, or how league_id is used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get), resource (scoring for matchups), and context (specific week). It is specific and informative, but does not explicitly differentiate from sibling tool 'get_matchups', which may have a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions 'in a specific week', providing minimal context. It gives no guidance on when to use this tool versus alternatives (e.g., get_matchups), when not to use it, or prerequisites such as league_id or week format.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current NFL season, week, and season type from Sleeper.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| leg | No | Current leg |
| week | No | Current week (0 in offseason) |
| season | Yes | Active season year |
| season_type | Yes | pre, regular, post, or off |
| display_week | No | Week to display in UI |
| previous_season | No | Prior season year |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description matches the annotations (readOnlyHint=true, openWorldHint=true) and accurately describes the behavior as a read operation. While it does not add extra behavioral details beyond the annotations, the tool's simplicity means no additional disclosure is necessary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose and returns exactly what the agent needs to know. No unnecessary words or information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema, the description succinctly states what is returned (season, week, season type), which is sufficient for the agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to add parameter details. Schema description coverage is 100%, meeting the baseline for no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the current NFL season, week, and season type from Sleeper' uses a specific verb ('Get') and clearly identifies the resource (NFL state) and the data fields returned (season, week, season type). It is distinct from sibling tools like get_user_leagues or get_league_info, which focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what the tool does, but does not explicitly mention when to use it versus alternatives. However, given its simplicity and the obvious context (retrieving current NFL state), the usage is self-evident and no conflicting alternatives exist among the listed siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a player's stats for a season (optionally one week).
| Name | Required | Description | Default |
|---|---|---|---|
| week | No | ||
| season | No | ||
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe, potentially varying read operation. The description adds that it covers a season with an optional week, but no additional behavioral traits like data freshness or result structure are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core purpose and the optional week feature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (one required) and an output schema that explains return values. The description covers the basic use case of getting player stats per season/week. While it could mention pagination or data limits, the output schema fills in the result details, making it reasonably complete for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only hints at the week parameter being optional. It does not explain the format of season (e.g., '2023' vs '2023-24'), the meaning of player_id, or the behavior when season is null. This leaves the agent to infer from parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'a player's stats', specifying the context of 'for a season (optionally one week)'. This distinguishes it from sibling tools like search_players or get_trending_players, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to use get_matchups for weekly stats or search_players for finding player IDs. The description only states what it does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a mapping of roster IDs to user names for a league.
| Name | Required | Description | Default |
|---|---|---|---|
| league_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, but the description adds no additional behavioral context (e.g., rate limits, pagination, or confirmation of read-only nature). Since the description does not contradict annotations and provides minimal extra transparency, it scores a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence of 8 words that communicates the tool's purpose without unnecessary detail. It is front-loaded and efficient, earning a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple parameter set, annotations covering read-only behavior, and an output schema (though not analyzed), the description provides the core purpose. However, it lacks details on prerequisites or error conditions, so it is slightly incomplete for a tool with zero schema description coverage, scoring a 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the tool description only adds the context 'for a league', which minimally clarifies that the league_id parameter identifies the league. This adds little meaning beyond the schema's type and title, resulting in a score of 2.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource as a 'mapping of roster IDs to user names' scoped to 'for a league'. This distinguishes it from siblings like 'get_league_rosters' and 'get_league_users' which provide separate lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the sibling tools (e.g., get_league_rosters, get_league_users). It only states the tool's function without any context for selection, scoring a 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get trending players (most added or dropped).
| Name | Required | Description | Default |
|---|---|---|---|
| sport | No | nfl | |
| add_drop | No | add |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read operation. The description adds only the concept of 'trending' but does not elaborate on data freshness, pagination, or limits. This is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and is concise. However, it could be slightly more structured (e.g., separating the parameter explanation). The brevity is valuable, but the lack of parameter details reduces efficiency for agents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (external to the description), so the omission of return format is acceptable. However, the description does not provide usage context (e.g., 'Use this to see popular player movements') or edge cases. It is minimally complete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The phrase 'most added or dropped' hints at the add_drop parameter but does not explicitly explain that 'add' returns most added players and 'drop' returns most dropped. The sport parameter is entirely undescribed. This provides minimal additional meaning beyond the enum and default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets trending players, with the parenthetical 'most added or dropped' directly linking to the add_drop parameter. This distinguishes it from tools like search_players (for specific player searches) and get_player_stats (for stats).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like search_players or get_player_stats. The sibling list is external, and the description itself lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all NFL leagues for a Sleeper username. Defaults to the current season.
| Name | Required | Description | Default |
|---|---|---|---|
| season | No | ||
| username | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's mention of 'Get' is consistent. It adds the default season behavior, which is useful, but does not disclose other traits like error handling or pagination. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the key action and default behavior. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description covers the essential: what it retrieves and the default season. It is adequate but could mention error scenarios or result format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate by detailing parameters. It only mentions 'username' and 'season' implicitly and notes the default, but provides no format or constraints, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('all NFL leagues'), and the scope ('for a Sleeper username'). It also adds the default behavior for season. This distinguishes it from sibling tools that focus on specific leagues or details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the required username and default season, but does not explicitly state when to use this tool versus alternatives like get_league_info. It lacks explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for players by name, with optional position filter.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| position | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and variability are covered. The description adds context about search behavior (by name, optional position) but does not disclose result limits or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence with no waste, front-loading the key purpose. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists to describe return values, the description is largely complete for a simple search tool. It covers the essential inputs without needing to detail outputs. Minor improvement could add fuzzy search behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It maps 'query' to 'by name' and 'position' to 'optional position filter', which adds some value. However, it doesn't elaborate on search semantics (e.g., case sensitivity, partial matches).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'players', with the optional position filter. It effectively distinguishes from sibling tools like get_player_stats or get_trending_players, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching players by name, optionally filtering by position, but lacks explicit guidance on when to use this tool versus alternatives. No direct comparison to siblings is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: state, leagues, rosters, users, drafts, players, matchups. No two tools overlap in functionality, even 'get_matchups' and 'get_matchup_scores' are distinct (scheduling vs. scoring).
Most tools follow 'get_<noun>' pattern, but 'search_players' uses 'search_' instead of 'get_'. This slight inconsistency is minor and does not hinder understanding.
13 tools cover the essential aspects of the Sleeper fantasy football platform without being excessive. Each tool addresses a specific data retrieval need, making the set well-scoped.
The server provides a comprehensive read-only surface for leagues, rosters, players, and matchups. Missing mutations (create/update/delete) are reasonable for a typical data retrieval tool, with minor gaps like waiver wire or trade info.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only ESPN, Sleeper, and Fantrax fantasy leagues for Claude, ChatGPT, and other AI tools.
Read-only fantasy analysis for ESPN, Yahoo, and Sleeper leagues via MCP
NFL analytics tools for AI agents: stats, fantasy, injuries, schedules, and advanced analysis.
NFL/NBA/MLB/NHL/PGA + DFS and prediction-market data. Browse free; query with a free API key.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sourknives/sleeper-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
