kicktipp-agent

A CLI and MCP server for kicktipp.com — the German football prediction game. View leaderboards, schedules, league tables, and place bets from the terminal or let an AI agent do it for you.

Why?

Kicktipp has no public API. Everything goes through the website. This project gives you two ways to skip the browser:

• CLI — Check scores, standings, and place bets in seconds from the terminal. No clicking through pages, no waiting for ads to load. Useful for quick lookups during matchday or scripting your predictions.

• MCP Server — Connect an AI assistant (Claude Desktop, Claude Code, or any MCP client) to your kicktipp account. Ask it to show today's matches, check who's leading your league, or place bets for you — all through natural conversation. The assistant sees your community's data but never your password.

Headless Chromium with session caching keeps things fast. After the first login, subsequent commands reuse the saved session and skip the login flow entirely.

Installation

npm install
npx playwright install chromium
npm run build
npm link

This gives you two commands:

• kicktipp — the CLI

• kicktipp-mcp — the MCP server

CLI

First-time setup

On first run, the CLI prompts for your kicktipp.com email and password. Credentials are stored locally in ~/.config/kicktipp-agent/config.ini (chmod 600).

$ kicktipp set-community
No credentials found. Please enter your kicktipp.com login:
Email: you@example.com
Password: ********
Credentials saved to ~/.config/kicktipp-agent/config.ini

Available communities:
  [1] testspiel
  [2] bundesliga-tipps
Select community (1-2): 1
Saved 'testspiel' as default community.

Optionally set your player name so the leaderboard highlights your position:

$ kicktipp set-player

Commands

Placing bets

# Interactive — prompts for each match
kicktipp bet

# By fixture name (get exact names from `kicktipp bets`)
kicktipp bet "FC Bayern München vs Borussia Dortmund=2:1"
kicktipp bet "RB Leipzig vs Bayer 04 Leverkusen=0:0" --matchday 5

# Bonus questions — interactive
kicktipp bet --bonus

# Bonus questions — by name
kicktipp bet --bonus "Who will win the league?=FC Bayern München"

Options

• --matchday <n> — Target a specific matchday (1-34)

• --bonus — Bonus question rankings (with leaderboard) or bonus bets (with bet)

• --view <value> — Overview type (with overview)

• --home / --away — Home/away filter (with table)

MCP Server

The MCP server exposes the same functionality as the CLI through the Model Context Protocol, allowing AI assistants like Claude to interact with kicktipp.com on your behalf.

Available tools

Setup with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "kicktipp": {
      "command": "kicktipp-mcp",
      "env": {
        "KICKTIPP_EMAIL": "you@example.com",
        "KICKTIPP_PASSWORD": "yourpassword"
      }
    }
  }
}

The env block passes credentials directly to the server process — Claude never sees them. If you prefer, you can omit env and set credentials via the CLI instead (kicktipp set-community).

After restarting Claude Desktop, the agent will have access to all kicktipp tools. It will call get_status first to check configuration, then prompt you to set a community if needed.

Setup with Claude Code

Add to .mcp.json in your home directory or project:

{
  "mcpServers": {
    "kicktipp": {
      "command": "kicktipp-mcp",
      "env": {
        "KICKTIPP_EMAIL": "you@example.com",
        "KICKTIPP_PASSWORD": "yourpassword"
      }
    }
  }
}

Credentials

The MCP server accepts credentials in two ways (checked in this order):

1. Environment variables — KICKTIPP_EMAIL and KICKTIPP_PASSWORD passed via the env block in your MCP client config

2. Config file — ~/.config/kicktipp-agent/config.ini, shared with the CLI

If neither is found, the server returns an error guiding the agent to inform you.

Development

npm test          # run tests
npm run build     # compile TypeScript

Credits

Originally forked from schwalle/kicktipp-betbot by Stefan. The project has since been fully rewritten in TypeScript with a new CLI interface, MCP server, and Cheerio-based parsing.