langchain-footballcharts

LangChain tools for football-charts.com — football statistics and model probabilities for 93 leagues (top flights, lower divisions and women's leagues on five continents), exposed as ten read-only agent tools.

pip install langchain-footballcharts

from langchain_footballcharts import FootballChartsToolkit

toolkit = FootballChartsToolkit(api_key="fc_...")   # or set FC_API_KEY
tools = toolkit.get_tools()

Get a free key in seconds at football-charts.com/developers — no card. The free tier covers all 93 leagues for the current and previous season.

What the tools return

Probabilities, not tips. Every model signal Football Charts publishes is logged before kickoff and settled in public; get_track_record returns that ledger unedited.

Example: an agent

from langchain.agents import create_agent
from langchain_anthropic import ChatAnthropic
from langchain_footballcharts import FootballChartsToolkit

agent = create_agent(
    ChatAnthropic(model="claude-sonnet-4-5"),
    tools=FootballChartsToolkit().get_tools(),
)
agent.invoke({"messages": [("user", "Which team in the Allsvenskan scores latest in matches?")]})

Notes

• Every tool has a sync _run and async _arun; results are JSON strings so the full payload reaches the model.
• The API key is bound per tool instance, never read from a module-level global.
• Goalless matches come back as first_goal_time: null, goalless: true.
• Same ten tools, same names, as the Football Charts MCP server.

Development

pip install -e ".[test]"
pytest tests/unit_tests                 # offline, mocked API
FC_API_KEY=fc_... pytest tests/integration_tests   # against production

MIT.