AI assistant setup
Use GridIron Data NFL fantasy data in your AI assistant (MCP)
Quick answer: GridIron Data runs a hosted MCP server at https://api.gridirondata.com/mcp. Add that URL to ChatGPT, Claude, Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Codex or any assistant that supports remote MCP servers, sign in with your GridIron Data account (or send your API key), and ask for NFL projections, stats, snap share, news, injuries and player-prop probabilities in plain English. Pick your assistant below for exact steps.
- Server URL
- https://api.gridirondata.com/mcp
- Transport
- Streamable HTTP
- Sign-in
- OAuth 2.1 or API key
- Tools
- 21
Which assistant do you use?
Each guide has the exact steps, example questions, troubleshooting and FAQs for that assistant.
| Assistant | How you add it | Sign-in |
|---|---|---|
| ChatGPT | Plugins → + → Add custom MCP server | OAuth |
| Claude (claude.ai and Desktop) | Customize → Connectors → Add custom connector | OAuth (API key header in beta) |
| Claude Code | claude mcp add --transport http … | OAuth or API key |
| Gemini (Gemini CLI) | gemini extensions install … (Gemini CLI) | OAuth or API key |
| GitHub Copilot (VS Code) | MCP: Add Server or .vscode/mcp.json | OAuth or API key |
| Cursor | ~/.cursor/mcp.json | OAuth or API key |
| OpenAI Codex | [mcp_servers] in ~/.codex/config.toml | OAuth or API key |
| Windsurf (Devin Desktop) | mcp_config.json (serverUrl) | API key |
| Microsoft Copilot Studio | Agent → Tools → Add a tool → Model Context Protocol | API key |
Using something else? Any client that speaks Streamable HTTP works: see any other MCP client. No remote MCP support at all? Run it locally.
What does it look like?
How does sign-in work?
You add the URL in your assistant. It opens a GridIron Data page where you sign in (email and password, Google or GitHub) and click Allow. You're sent back, connected. No account yet? Sign up free, or create one on the sign-in screen.
The assistant gets a token that works only for this server, expires after an hour and renews itself. It never sees your password or your API key. Every call runs on your account, so your plan and monthly quota apply exactly as they do for the API. To disconnect, remove the connection in the assistant.
Assistants without OAuth sign-in use your API key from the dashboard instead, sent as Authorization: Bearer YOUR_KEY or x-api-key: YOUR_KEY. Keep a key in a header or your client's secret store, never in a URL.
How do I connect any other MCP client?
Point it at https://api.gridirondata.com/mcp over Streamable HTTP. Many clients read an mcpServers JSON block like this:
{
"mcpServers": {
"gridiron-data": {
"url": "https://api.gridirondata.com/mcp"
}
}
}
If the client supports MCP OAuth, it shows a sign-in or Connect step. If not, add your key as a header (the key name for headers varies by client; check its docs):
{
"mcpServers": {
"gridiron-data": {
"url": "https://api.gridirondata.com/mcp",
"headers": { "Authorization": "Bearer YOUR_KEY" }
}
}
}
OAuth sign-in sends you back to the assistant at the end, so GridIron only accepts return addresses for clients it knows (ChatGPT, Claude, Cursor, VS Code, and desktop or command-line apps that listen on localhost). If sign-in from another web-based client stops with "redirect URI not allowed", use your API key in a header, or email info@gridirondata.com to have that client added.
Can I run it locally instead (stdio)?
Yes. The same tools run as a single local file, for clients without remote MCP or if you'd rather keep it on your machine. You need your API key from the dashboard and uv.
curl -o gridiron-mcp.py https://www.gridirondata.com/gridiron-mcp.py
Register it with your client as a stdio server that runs uv run /absolute/path/to/gridiron-mcp.py with GRIDIRON_API_KEY set. For example, in Claude Code (-s user makes it available in every project):
claude mcp add gridiron-data -s user \
-e GRIDIRON_API_KEY=YOUR_KEY \
-- uv run "$(pwd)/gridiron-mcp.py"
Or in any mcpServers JSON client:
{
"mcpServers": {
"gridiron-data": {
"command": "uv",
"args": ["run", "/absolute/path/to/gridiron-mcp.py"],
"env": { "GRIDIRON_API_KEY": "YOUR_KEY" }
}
}
}
uv run installs the one dependency (the MCP SDK) from the file's header the first time it launches. Without uv:
python3 -m venv gridiron-mcp-venv
gridiron-mcp-venv/bin/pip install "mcp>=2,<3"
claude mcp add gridiron-data -s user \
-e GRIDIRON_API_KEY=YOUR_KEY \
-- "$(pwd)/gridiron-mcp-venv/bin/python" "$(pwd)/gridiron-mcp.py"
What can my assistant pull? (24 tools)
| Tool | What it returns | Plan |
|---|---|---|
get_projections | weekly projections (PPR / half / standard) | Free for this week; Basic for other weeks; Pro adds per-stat lines |
get_player_stats | 2020-present weekly and season actuals | Basic |
search_players / get_player / list_players | find and read player profiles | Free |
get_player_by_espn_id / get_player_by_gsis_id | look a player up by ESPN athlete id or NFL GSIS id | Free |
get_deviations | boom/bust: actual vs projected | Basic |
get_matchups | a player's history against an opponent | Basic |
get_snap_share | per-week snap share and role-change trend | Basic |
get_player_news / request_news_scrape / get_latest_news | impact-tagged player news and the league-wide feed | Basic |
get_ros_projections | rest-of-season projected points | Basic |
get_schedule / get_byes | NFL schedule, scores and bye weeks | Basic; Pro adds each game's betting line |
get_coverage_splits / get_defense_coverage / get_coverage_matchup | receiver splits against man vs zone and coverage shells, a defense's coverage mix and blitz rate, and a receiver vs this week's opponent. Man/zone and shells are the 2025 season (nflverse has no 2026 file yet); blitz splits are 2026 to date. No slot/wide alignment. | Basic |
get_prop_probability | P(over/under) and fair no-vig odds for a player stat line | Pro |
get_defense_vs_position | what each defense allows by position | Pro |
get_injury_changes | injury status changes since a time, checked every 2 minutes | Pro |
get_depth_chart | every team's depth chart and starters (first in each slot), with each player's injury status, as of the daily nflverse refresh | Pro |
get_inactives | official game-day inactives, published after the games, for audit and backtesting | Pro |
A tool outside your plan answers with the plan it needs and a link to the plans, and the assistant tells you. Player names, positions and ids are matched case-insensitively. Prop probabilities are a model estimate, not betting advice.
Try: "What are the top 10 RB projections this week in half-PPR?", "How did Justin Jefferson do in 2023?", "Any injury news on Malik Nabers this week?", or "What's the chance Drake Maye throws over 245.5 yards this week?" (Pro).
Troubleshooting
- Sign-in page says the link expired. The sign-in has 15 minutes. Start again from your assistant (Connect / Authenticate).
- Asked to sign in again. You regenerated your API key, your plan ended, or you haven't used the connection for 30 days. Reconnect and sign in.
- "unauthorized" with an API key. The key is missing or wrong. Check it on your dashboard (regenerating a key retires the old one).
- "Not available on this account's current plan". That question needs Basic or Pro; see plans.
- "redirect URI not allowed" during sign-in. Your client isn't on the sign-in allowlist yet. Use your API key in a header, or email info@gridirondata.com.
- Local server won't start. Use an absolute path to
gridiron-mcp.py, and make sureuv(or your venv Python) is on your PATH.
Frequently asked questions
Which AI assistants can use GridIron Data?
Any assistant that can add a remote MCP server over Streamable HTTP. There are step-by-step guides for ChatGPT, Claude (claude.ai and Desktop), Claude Code, Gemini (Gemini CLI), GitHub Copilot (VS Code), Cursor, OpenAI Codex, Windsurf (Devin Desktop) and Microsoft Copilot Studio. Each connects to the same URL, https://api.gridirondata.com/mcp.
Do I need an API key to connect?
Not in assistants that support OAuth sign-in (ChatGPT, Claude, Claude Code, Gemini CLI, GitHub Copilot in VS Code, Cursor, Codex CLI): you sign in with your GridIron Data account and click Allow. Assistants that only take a header use your API key as Authorization: Bearer YOUR_KEY or x-api-key. Either way, calls run on your account and plan.
Is it free?
A free GridIron Data account (no credit card) answers player lookups and this week's projections. Stats, snaps, news, matchups, the schedule and other weeks need Basic ($5/month or $45/year); prop probabilities, defense vs position, betting lines and the injury-changes feed need Pro ($29/month or $249/year). Your assistant's own plan rules apply too.
Does the assistant see my password or API key?
With OAuth sign-in, no. The assistant gets a token that works only for this server, expires after an hour and renews itself. With the API-key option, the key sits in your assistant's config or secret store, so keep it out of shared files.
Can I run the server locally instead?
Yes. The same tools run from a single Python file, https://www.gridirondata.com/gridiron-mcp.py, over stdio with your API key in GRIDIRON_API_KEY. The hosted server always has the newest tools; a downloaded copy needs downloading again.