parmacalcio1913/event-data-chatbot

This project is a command-line chatbot that lets you ask plain-English questions about professional football match data. You type something like "Who scored the most goals in the 2015/2016 La Liga?" and the bot figures out what data to look up and gives you an answer, without you needing to write any database queries yourself. The data comes from StatsBomb, a football analytics company that publishes a free open dataset covering dozens of competitions and thousands of matches. The project downloads a local copy of that dataset (about half a gigabyte) and stores it in a database on your own machine. All queries run locally after that. Under the hood, the chatbot connects Claude, an AI model from Anthropic, to that local database through a system called MCP (Model Context Protocol). When you ask a question, Claude decides what data it needs, writes a SQL query internally, runs it against the database, reads the result, and then writes a plain-English answer back to you. You never see the SQL unless you turn on a debug flag. The same loop can run multiple queries in a row if your question requires it, for example first checking which competition names exist and then running a follow-up count. There is also a slash-command feature. Typing /summary followed by a match ID produces a structured match report for that specific game. The project includes tab completion so you can discover available commands by pressing Tab. To use it you need Python 3.10 or newer and an Anthropic API key, which requires a paid account with Anthropic. Setup involves cloning the repository, installing dependencies, downloading the StatsBomb snapshot, and adding your API key to a configuration file. The README includes step-by-step instructions for each of those steps. The code is released under the MIT license. The StatsBomb data itself is subject to a separate user agreement that requires attribution and display of the StatsBomb logo if you publish any analysis derived from it.