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.

Setup guides by AI assistant
AssistantHow you add itSign-in
ChatGPTPlugins → + → Add custom MCP serverOAuth
Claude (claude.ai and Desktop)Customize → Connectors → Add custom connectorOAuth (API key header in beta)
Claude Codeclaude 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.jsonOAuth or API key
Cursor~/.cursor/mcp.jsonOAuth or API key
OpenAI Codex[mcp_servers] in ~/.codex/config.tomlOAuth or API key
Windsurf (Devin Desktop)mcp_config.json (serverUrl)API key
Microsoft Copilot StudioAgent → Tools → Add a tool → Model Context ProtocolAPI 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?

Connecting GridIron Data in Claude, then asking for week 8 receiver projections and a player-prop probability (1:06, with captions).
One command adds GridIron Data to Claude Code, then two questions answered from live data (1:14, with captions). Also on YouTube.

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)

GridIron Data MCP tools and the lowest plan for each
ToolWhat it returnsPlan
get_projectionsweekly projections (PPR / half / standard)Free for this week; Basic for other weeks; Pro adds per-stat lines
get_player_stats2020-present weekly and season actualsBasic
search_players / get_player / list_playersfind and read player profilesFree
get_player_by_espn_id / get_player_by_gsis_idlook a player up by ESPN athlete id or NFL GSIS idFree
get_deviationsboom/bust: actual vs projectedBasic
get_matchupsa player's history against an opponentBasic
get_snap_shareper-week snap share and role-change trendBasic
get_player_news / request_news_scrape / get_latest_newsimpact-tagged player news and the league-wide feedBasic
get_ros_projectionsrest-of-season projected pointsBasic
get_schedule / get_byesNFL schedule, scores and bye weeksBasic; Pro adds each game's betting line
get_coverage_splits / get_defense_coverage / get_coverage_matchupreceiver 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_probabilityP(over/under) and fair no-vig odds for a player stat linePro
get_defense_vs_positionwhat each defense allows by positionPro
get_injury_changesinjury status changes since a time, checked every 2 minutesPro
get_depth_chartevery team's depth chart and starters (first in each slot), with each player's injury status, as of the daily nflverse refreshPro
get_inactivesofficial game-day inactives, published after the games, for audit and backtestingPro

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 sure uv (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.