Fantasy Football Data MCP Server
Click on "Deploy 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., "@Fantasy Football Data MCP ServerWhat are the week projections for player ID 1234?"
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.
Fantasy Football Data MCP Server with Sportmicro API
A read-only Model Context Protocol server for fantasy-football research that exposes grounded football data from Sportmicro. It is designed for developers who want fantasy football MCP server workflows backed by documented Sportmicro endpoints instead of invented data.
The server uses the official @modelcontextprotocol/sdk with stdio transport and a typed Sportmicro football client. It validates inputs, keeps the API narrow, and returns source-shaped data for supported player, team, fixture, and statistics queries.
Sportmicro documentation used by this project: https://docs.sportmicro.com/
Features
Fantasy-data research MCP tools
Player, team, and fixture queries when documented
Typed source-data responses
Clear scope boundaries
Input validation
Read-only operation
Related MCP server: sleeper-mcp
What this server does
This project focuses on a small set of documented Sportmicro football resources:
playersteamsmatchesplayers-statisticsplayer-projectionsplayer-projections-weekplayer-projections-season
The server intentionally does not claim fantasy scoring, transfers, or broader football workflows unless they are directly backed by documented Sportmicro endpoints.
Prerequisites
Node.js 18 or newer
An API key from Sportmicro
Installation
npm installEnvironment variables
Create a local .env file or export the environment variable directly:
SPORTMICRO_API_KEY=your_key_hereA template is included in .env.example.
Run
Build the project and start the MCP server via stdio:
npm run build
node dist/index.jsThe process is intended to be launched by an MCP client that connects over stdio.
Available MCP tools
This repository exposes narrow read-only tools for Sportmicro football data:
sportmicro_get_playerssportmicro_get_teamssportmicro_get_matchessportmicro_get_player_statisticssportmicro_get_player_projectionssportmicro_get_player_projections_weeksportmicro_get_player_projections_season
Each tool validates its input and returns structured results with a meta block that describes the query and record count.
Example usage
A client can request players for a team like this:
{
"team_id": "123",
"limit": 10
}Example response shape:
{
"items": [],
"meta": {
"resource": "players",
"query": {
"team_id": "123",
"limit": 10
},
"count": 0,
"empty": true
}
}Project structure
src/
index.ts MCP server entrypoint
config.ts Environment validation
sportmicro/
client.ts Typed Sportmicro football client
schemas.ts Runtime validation and request schemas
types.ts Shared TypeScript types
tools/
registry.ts MCP tool registration and handlers
resource-format.ts Normalized response helpers
test/
sportmicro-client.test.ts
tool-contracts.test.tsBuild
npm run buildTest
npm testTests use mocked Sportmicro responses and verify the tool contracts without making live API calls.
API usage notes
Supported requests are limited to the documented Sportmicro football endpoints listed above. This repository does not invent endpoints or fields. If Sportmicro returns empty, partial, or unavailable data, the server preserves that state so clients can handle it explicitly.
Known limitations
Only the documented read-only football endpoints are supported.
The server does not implement fantasy scoring, transfers, or betting advice.
Live coverage is limited to the endpoints documented by Sportmicro.
Response fields are normalized only enough to provide safe, typed access without claiming undocumented semantics.
License
MIT
Available Tools
7 toolssportmicro_get_matchesB
Get documented Sportmicro football matches with optional filters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose authentication needs, rate limits, pagination, or what 'documented' means for coverage. Essentially only the read-like verb 'Get' hints at behavior.
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?
A single front-loaded sentence with no wasted words. It is efficient, though its brevity comes at the cost of specificity rather than being over-long.
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 no annotations, no output schema, no defined parameters, and siblings covering adjacent domains, the description leaves substantial gaps. An agent cannot tell what filters are accepted or what a match record contains.
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?
Parameter count is 0, so the baseline is 4. The mention of 'optional filters' is consistent with an open schema (additionalProperties: true), though the description does not name any filter, which is a minor gap rather than a schema-level deficiency.
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?
States a specific verb and resource ('Get ... football matches'), which is distinguishable from the sibling tools that cover players, teams, and statistics. The qualifier 'documented' is vague and adds no actionable meaning, but the core purpose is clear.
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 mentions 'optional filters' but never says when to use this tool over the sibling match/player/team endpoints, nor what context or prerequisites apply. No when-to-use or when-not-to-use guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sportmicro_get_player_projectionsC
Get documented Sportmicro player projections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. It doesn't say whether results are read-only snapshots, how projections are scoped (games, dates, players), or what the response contains. 'Documented' hints at some curation but is not explained.
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?
A single short sentence with no wasted words, and the verb+resource is front-loaded. It is efficient, though its brevity reflects under-specification rather than disciplined editing.
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 zero-parameter getter with no annotations and no output schema, the description should at minimum clarify what 'projections' covers and how it relates to the week/season siblings. That critical disambiguation is missing.
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 takes zero parameters, so there is nothing for the description to clarify. The baseline of 4 applies.
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?
States a clear verb ('Get') and resource ('player projections'), so the basic operation is identifiable. However, the qualifier 'documented' is vague and the description does nothing to distinguish this tool from the sibling sportmicro_get_player_projections_week and _season variants, so an agent cannot tell which projection set this returns.
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?
There is no guidance on when to use this tool versus the week/season projection siblings, nor any stated prerequisites or context. The agent is left to infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sportmicro_get_player_projections_seasonC
Get documented Sportmicro season player projections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses nothing: no data source or freshness, no season definition, no permissions or rate limits, no statement of whether results are live or cached. 'Documented' hints at provenance but never explains it.
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?
It is a single six-word front-loaded sentence with no padding or repetition. The only wasted token is the vague modifier 'documented', but there is no verbosity to penalize.
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 no-parameter tool with no annotations and no output schema, the description must convey scope and return expectations on its own. It does not: what 'season' spans, the projection metrics returned, and how it differs from the week-level sibling are all missing.
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 takes zero parameters, and the schema is a bare permissive object with additionalProperties=true, so there are no parameter semantics the description could add. The baseline of 4 applies because there is nothing to document.
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 gives a clear verb and resource ('Get ... player projections') and the word 'season' is the attribute that distinguishes it from sportmicro_get_player_projections_week, but it never makes that contrast explicit and 'documented' is unearned filler rather than a meaningful qualifier.
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?
There is no when-to-use guidance at all. With three closely related siblings (get_player_projections, get_player_projections_week, and this season variant), the description offers no criteria for choosing among them, leaving the agent to infer scope from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sportmicro_get_player_projections_weekB
Get documented Sportmicro weekly player projections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about what is returned, whether the data is current or historical, or any freshness/rate constraints. Only the word 'Get' hints that this is a read operation.
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?
A single front-loaded sentence with no padding, which is appropriate for a no-arg read tool. The word 'documented' is the only element that fails to earn its place.
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 no output schema, no annotations, and three closely related projection siblings, the description is too thin to tell an agent what distinguishes the weekly view or what it receives back. It leaves the core selection question unresolved.
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 takes zero parameters (schema is an open object with additionalProperties true), so there is nothing for the description to document and the baseline of 4 applies. No parameter ambiguity is introduced.
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 phrase 'Get ... weekly player projections' gives a clear verb and resource, and 'weekly' implicitly separates it from sportmicro_get_player_projections_season. However, it never explicitly states the distinction, and the odd qualifier 'documented' adds noise rather than precision.
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?
There is no when-to-use guidance, no exclusions, and no mention of the near-identical siblings sportmicro_get_player_projections and sportmicro_get_player_projections_season. The agent must infer the weekly/season split purely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sportmicro_get_playersC
Get documented Sportmicro football players with optional filters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about pagination, result size, auth requirements, or whether the call is read-only. It also never explains what 'documented' players means or what happens when filters match nothing.
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?
A single front-loaded sentence with no filler or repetition. The only waste is the ambiguous qualifier 'documented', which adds no actionable 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?
There is no output schema, no annotations, and no parameter definitions, so the description is the sole source of information — and it omits the return shape, filter mechanism, and result limits. For a data-retrieval tool sitting beside five sibling lookups, this is under-specified.
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 zero declared parameters the baseline is 4, but the description promises 'optional filters' while the schema exposes only additionalProperties:true with no named filter fields. That leaves an agent guessing at the accepted filter syntax, which is a real gap rather than neutral silence.
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?
States a specific verb+resource (get ... players) and names the domain entity ('Sportmicro football players'), which is enough to separate it from sportmicro_get_teams and sportmicro_get_matches. It does not, however, state how it differs from the adjacent player-data siblings (get_player_statistics, get_player_projections), and the modifier 'documented' is undefined.
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 offers no when-to-use guidance, no prerequisites, and does not name any alternative for retrieving player statistics or projections. 'With optional filters' hints that filtering is possible but never says when this tool is preferred over the player-specific siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sportmicro_get_player_statisticsC
Get documented Sportmicro player statistics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full behavioral burden, and it discloses almost nothing: no auth requirements, no rate limits, no statement of whether the result is a single player or a batch, and no indication of what 'documented' means. It does not contradict anything, but it adds no behavioral context.
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?
A single short, front-loaded sentence with no wasted clauses. It is efficient, though 'documented' is filler that could have been replaced with substantive scope 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 zero-parameter tool with no annotations and no output schema, the description is the only source of information, and it says nothing about what fields are returned, which players are covered, or how results are scoped. The open 'additionalProperties: true' schema also leaves the agent unsure whether filtering is even possible, and the description never resolves 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?
The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. The schema is an unconstrained object, so no parameter detail is being missed.
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 names a verb ('Get') and a resource ('player statistics'), which separates it on paper from the projections siblings in the same family. However, the qualifier 'documented' is undefined and no scope (season, game, aggregation level) is given, so the agent cannot tell what statistics actually come back.
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?
There is no guidance on when to use this tool rather than sportmicro_get_player_projections, _week, _season, or _get_players. The agent must infer the distinction between historical statistics and projections on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sportmicro_get_teamsC
Get documented Sportmicro football teams with optional filters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It doesn't disclose authentication requirements, pagination, response size, or what 'documented' teams means (complete league coverage vs. a curated subset), and the promised filters are never described.
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?
A single efficient sentence with the verb and resource front-loaded and no filler. It is appropriately sized; the only weakness is that brevity here comes from omission rather than precision.
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 annotations, no output schema, and no documented parameters, the definition supplies no return-shape information, no data-freshness context, and no clarification of the promised filters. Too much of what an agent needs to call it correctly is left unspecified.
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 zero declared parameters the baseline would be 4, but the description promises 'optional filters' that the input schema does not define at all — the schema is an open object with no properties. An agent may attempt filter arguments that are silently ignored under additionalProperties=true, so the description creates a small mismatch rather than added clarity.
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 names a specific verb (Get) and resource (football teams) scoped to the Sportmicro data source, which lets an agent separate it from siblings like sportmicro_get_players and sportmicro_get_matches by resource alone. It stops short of stating what distinguishes it beyond the noun, but the purpose is unambiguous.
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 phrase 'with optional filters' hints that filtering is possible but names no filter, no scenario, and no alternative tool. There is no guidance on when to call this versus the other sportmicro_get_* endpoints; the agent must infer everything from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v1.0.0- First observed
sportmicro_get_matches - First observed
sportmicro_get_player_projections - First observed
sportmicro_get_player_projections_season - First observed
sportmicro_get_player_projections_week - First observed
sportmicro_get_player_statistics - First observed
sportmicro_get_players - First observed
sportmicro_get_teams
TDQS
Scored across 7 tools
Three projection tools (player_projections, player_projections_week, player_projections_season) overlap heavily and their boundaries are unclear from descriptions. No explanation of how a general projection tool differs from the week/season variants.
All tools follow a consistent sportmicro_get_<resource> pattern with snake_case, which is predictable and readable.
Seven tools is well-scoped for a data retrieval server, covering core entities without bloat.
Only read operations are present; no create/update/delete despite 'Data MCP Server' implying management. Also missing key fantasy entities like leagues, drafts, and matchups.
Maintenance
Related MCP Connectors
Sports MCP — wraps TheSportsDB API (free tier, test key 3, no auth required)
API-Football MCP — comprehensive soccer/football data
Read-only fantasy analysis for ESPN, Yahoo, and Sleeper leagues via MCP
Pro football play-by-play, stats, injuries, and odds. REST API and MCP server. Free to start.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides read-only access to Sleeper fantasy football leagues, enabling team snapshots, available players, matchups, trade context, and league history through standardized MCP tools.MIT
- FlicenseAqualityCmaintenanceEnables read-only access to Sleeper fantasy sports data, including users, leagues, rosters, matchups, transactions, drafts, players, trending activity, playoff brackets, traded picks, and sport state via MCP tools.18-
- FlicenseNot gradedqualityBmaintenanceProvides live football data from API-Football over HTTP, enabling queries for upcoming matches, recent results, current standings, injuries, live matches, and team search through MCP tools.-
- AlicenseAqualityCmaintenanceEnables agents to retrieve live NFL scores, Wire news, Scout player grades, start/sit recommendations, and rankings through read-only MCP tools.511 PyPIMIT