kicktipp-ai

Automated Kicktipp football tipping. Ships in two flavours:

• MCP server — exposes Kicktipp tools to Claude Desktop (or any MCP client) so you can ask Claude to look at open matches and submit predictions.
• CLI bot — a standalone script that fills in tips on a schedule using a built-in strategy.

⚠️ Use responsibly and at your own risk. Automating logins to a third-party site may be against Kicktipp's terms of service. This is a personal hobby project.

Features

The MCP server (mcp_server.py) provides three tools:

• list_open_matches — matches that still need a tip (not yet kicked off, not already tipped)
• list_submitted_tips — tips you've already submitted
• submit_tips — post predicted home/away scores

The CLI bot (main.py) supports two strategies:

• random — weighted Poisson scoreline sampling
• llm — shells out to the Claude Code CLI (claude -p) to predict scores with web search

Requirements

• Python 3.10+
• uv (recommended) or plain pip
• A Kicktipp account and a community you're a member of
• For the llm strategy: the Claude Code CLI on your PATH

Setup

1. Install dependencies

   uv sync          # or: pip install -e .
   

2. Configure credentials

   cp .env.example .env
   

   Then edit .env with your Kicktipp email, password, and community slug. The community slug is the path segment in your community URL — for https://www.kicktipp.de/my-community/ it's my-community.

   .env is git-ignored; never commit it.

Usage

CLI bot

# Dry run — print tips without submitting
uv run python main.py --strategy random --dry-run

# Submit tips for matches starting within the next 48 hours
uv run python main.py --strategy random --max-hours-ahead 48

# Use the LLM strategy (requires the claude CLI)
uv run python main.py --strategy llm

Run uv run python main.py --help for all options (--community, --debug-html, …).

Scheduled runs (macOS launchd)

com.kicktipp-ai.bot.plist runs the bot every 6 hours via launchd.

1. Edit the plist and replace /absolute/path/to/kicktipp-ai with your real path.

2. Copy it into place and load it:

   cp com.kicktipp-ai.bot.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/com.kicktipp-ai.bot.plist
   

Logs are written to /tmp/kicktipp-ai.log.

MCP server (Claude Desktop)

1. Edit claude_desktop_config.example.json and replace the placeholder path with the absolute path to run-mcp.sh.
2. Merge its contents into your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json.
3. Restart Claude Desktop.

You can then ask Claude to list open matches and submit tips for you.

Project layout

| File | Purpose | |------|---------| | kicktipp.py | Kicktipp HTTP client + HTML parsing | | mcp_server.py | FastMCP server exposing the tools | | main.py | CLI entry point for the bot | | strategies.py | Tipping strategies (random / llm) | | run-mcp.sh | Launcher Claude Desktop uses for the MCP server | | run.sh | Launcher the launchd job uses for the CLI bot |

License

MIT — see LICENSE.