# boardgamefyi

[![PyPI version](https://agentgif.com/badge/pypi/boardgamefyi/version.svg)](https://pypi.org/project/boardgamefyi/)
[![Python](https://img.shields.io/pypi/pyversions/boardgamefyi)](https://pypi.org/project/boardgamefyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/boardgamefyi/)

Python API client for [boardgamefyi.com](https://boardgamefyi.com/) -- the comprehensive board game database covering games, designers, publishers, mechanics, categories, awards, and game night themes. Access game profiles, progression paths, glossary terms, and guides through a free REST API, CLI, or MCP server for AI assistants.

[BoardGameFYI](https://boardgamefyi.com/) catalogs board games with detailed mechanics classifications, designer and artist credits, publisher data, award histories, and curated game night themes -- built for developers, game enthusiasts, and content creators who need structured tabletop gaming data.

> **Explore board games at [boardgamefyi.com](https://boardgamefyi.com/)** -- browse games, compare mechanics, and discover game night themes.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/boardgamefyi/main/demo.gif" alt="boardgamefyi demo -- board game database API client for Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Browse Games and Mechanics](#browse-games-and-mechanics)
  - [Designers, Artists, and Publishers](#designers-artists-and-publishers)
  - [Game Night Themes and Progression Paths](#game-night-themes-and-progression-paths)
  - [Awards and Recognition](#awards-and-recognition)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Board Games](#learn-more-about-board-games)
- [Guide FYI Family](#guide-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
pip install boardgamefyi              # Core (zero deps)
pip install "boardgamefyi[cli]"       # + Command-line interface
pip install "boardgamefyi[mcp]"       # + MCP server for AI assistants
pip install "boardgamefyi[api]"       # + HTTP client for boardgamefyi.com API
pip install "boardgamefyi[all]"       # Everything
```

## Quick Start

```python
from boardgamefyi.api import BoardGameFYI

with BoardGameFYI() as api:
    # List games in the database
    games = api.list_games()

    # Get detailed info for a specific game
    catan = api.get_game("catan")

    # Browse game mechanics
    mechanics = api.list_mechanics()
    worker_placement = api.get_mechanic("worker-placement")

    # Search across all board game content
    results = api.search("cooperative")
```

## What You Can Do

### Browse Games and Mechanics

Board games are classified by their core mechanics -- the fundamental actions players take during gameplay. A single game often combines multiple mechanics. Worker placement, deck building, area control, and engine building are among the most popular modern euro-game mechanics. Understanding mechanics helps players find games matching their preferences.

| Mechanic | Description | Example Games |
|----------|-------------|---------------|
| Worker Placement | Assign limited workers to action spaces | Agricola, Viticulture, Caverna |
| Deck Building | Build a personal deck during play | Dominion, Star Realms, Clank! |
| Area Control | Contest and claim map regions | Risk, Twilight Imperium, Kemet |
| Engine Building | Create combos that grow in power | Terraforming Mars, Wingspan, Splendor |
| Cooperative | All players work together vs the game | Pandemic, Spirit Island, Gloomhaven |
| Dice Rolling | Random outcomes via dice | King of Tokyo, Sagrada, Dice Forge |
| Tile Placement | Place tiles to build a shared board | Carcassonne, Azul, Cascadia |
| Hand Management | Optimize card usage from hand | 7 Wonders, Race for the Galaxy |

```python
from boardgamefyi.api import BoardGameFYI

# Explore game mechanics and their classifications
with BoardGameFYI() as api:
    mechanics = api.list_mechanics()
    deck_building = api.get_mechanic("deck-building")

    # Browse games by category
    categories = api.list_categories()
    strategy = api.get_category("strategy")
```

Learn more: [Browse Games](https://boardgamefyi.com/) · [Glossary](https://boardgamefyi.com/glossary/) · [Guides](https://boardgamefyi.com/guides/)

### Designers, Artists, and Publishers

Board game design is a collaborative process involving game designers (who create mechanics and rules), artists (who create visual identity), and publishers (who produce and distribute). Some designers like Uwe Rosenberg and Reiner Knizia have designed hundreds of games, while others are known for a single groundbreaking title.

| Role | Contribution | Notable Names |
|------|-------------|--------------|
| Designer | Game mechanics, rules, balance | Uwe Rosenberg, Reiner Knizia, Vlaada Chvatil |
| Artist | Box art, card art, board illustrations | Vincent Dutrait, Andrew Bosley, Beth Sobel |
| Publisher | Production, distribution, marketing | Stonemaier Games, Asmodee, Czech Games Edition |
| Developer | Playtesting, balance refinement | Often in-house at publishers |

```python
from boardgamefyi.api import BoardGameFYI

# Explore designers, artists, and publishers
with BoardGameFYI() as api:
    designers = api.list_designers()
    knizia = api.get_designer("reiner-knizia")

    artists = api.list_artists()
    publishers = api.list_publishers()
    stonemaier = api.get_publisher("stonemaier-games")
```

Learn more: [Designers](https://boardgamefyi.com/) · [Publishers](https://boardgamefyi.com/) · [API Docs](https://boardgamefyi.com/developers/)

### Game Night Themes and Progression Paths

Game night themes are curated collections of games organized around a theme, player count, or experience level. Progression paths guide new players from gateway games (simple rules, short playtime) through mid-weight strategy games to heavy euro-games. This approach helps build gaming groups by matching complexity to experience.

| Weight Class | Complexity | Play Time | Example Games |
|-------------|-----------|-----------|---------------|
| Light (1.0 -- 2.0) | Few rules, quick to learn | 15 -- 30 min | Ticket to Ride, Codenames, Azul |
| Medium-Light (2.0 -- 2.5) | Moderate decisions, accessible | 30 -- 60 min | Catan, Wingspan, Carcassonne |
| Medium (2.5 -- 3.5) | Strategic depth, longer rules | 60 -- 120 min | Terraforming Mars, Viticulture |
| Heavy (3.5 -- 4.5) | Complex systems, steep learning | 120 -- 240 min | Gaia Project, Brass: Birmingham |
| Very Heavy (4.5+) | Deep simulation, many rules | 240+ min | Twilight Imperium, Through the Ages |

```python
from boardgamefyi.api import BoardGameFYI

# Explore game night themes and progression paths
with BoardGameFYI() as api:
    themes = api.list_game_night_themes()
    family_night = api.get_game_night_theme("family-game-night")

    paths = api.list_progression_paths()
    euro_path = api.get_progression_path("euro-games")
```

Learn more: [Game Night Themes](https://boardgamefyi.com/) · [Progression Paths](https://boardgamefyi.com/) · [Guides](https://boardgamefyi.com/guides/)

### Awards and Recognition

Board game awards recognize excellence in design, art, and innovation. The Spiel des Jahres (Game of the Year) in Germany is considered the most prestigious award in the industry and can drive sales of 300,000+ copies for the winner. The Kennerspiel des Jahres recognizes more complex "connoisseur" games.

| Award | Country | Focus | Notable Winners |
|-------|---------|-------|----------------|
| Spiel des Jahres | Germany | Family game of the year | Cascadia, MicroMacro, Codenames |
| Kennerspiel des Jahres | Germany | Connoisseur game of the year | Dune: Imperium, Paleo, Wingspan |
| Deutscher Spielepreis | Germany | Voted by gamers and critics | Ark Nova, Gloomhaven |
| Golden Geek Awards | International (BGG) | Community-voted categories | Spirit Island, Brass: Birmingham |
| Origins Awards | USA | Best board game, card game | Various categories |

```python
from boardgamefyi.api import BoardGameFYI

# Browse awards and recognition
with BoardGameFYI() as api:
    awards = api.list_awards()
    sdj = api.get_award("spiel-des-jahres")

    # Access interactive tools for game selection
    tools = api.list_tools()
```

Learn more: [Awards](https://boardgamefyi.com/) · [FAQs](https://boardgamefyi.com/) · [Glossary](https://boardgamefyi.com/glossary/)

## Command-Line Interface

```bash
pip install "boardgamefyi[cli]"

# Search for board games
boardgamefyi search "cooperative strategy"

# Output is JSON for easy piping
boardgamefyi search "Wingspan" | jq '.results[0]'
```

## MCP Server (Claude, Cursor, Windsurf)

Add board game data tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).

```bash
pip install "boardgamefyi[mcp]"
```

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "boardgamefyi": {
            "command": "python",
            "args": ["-m", "boardgamefyi.mcp_server"]
        }
    }
}
```

**Available tools**: `search_boardgamefyi`

## REST API Client

```python
from boardgamefyi.api import BoardGameFYI

with BoardGameFYI() as api:
    # List endpoints
    games = api.list_games()
    mechanics = api.list_mechanics()
    categories = api.list_categories()
    designers = api.list_designers()
    artists = api.list_artists()
    publishers = api.list_publishers()
    awards = api.list_awards()
    glossary = api.list_glossary()
    guides = api.list_guides()

    # Detail endpoints
    game = api.get_game("catan")
    mechanic = api.get_mechanic("worker-placement")

    # Search
    results = api.search("2 player")
```

## API Reference

| Method | Description |
|--------|-------------|
| `list_games(**params)` | List all board games |
| `get_game(slug)` | Get game detail |
| `list_mechanics(**params)` | List all game mechanics |
| `get_mechanic(slug)` | Get mechanic detail |
| `list_categories(**params)` | List all categories |
| `get_category(slug)` | Get category detail |
| `list_designers(**params)` | List all designers |
| `get_designer(slug)` | Get designer detail |
| `list_artists(**params)` | List all artists |
| `get_artist(slug)` | Get artist detail |
| `list_publishers(**params)` | List all publishers |
| `get_publisher(slug)` | Get publisher detail |
| `list_awards(**params)` | List all awards |
| `get_award(slug)` | Get award detail |
| `list_game_night_themes(**params)` | List game night themes |
| `get_game_night_theme(slug)` | Get game night theme detail |
| `list_progression_paths(**params)` | List progression paths |
| `get_progression_path(slug)` | Get progression path detail |
| `list_tools(**params)` | List interactive tools |
| `get_tool(slug)` | Get tool detail |
| `list_glossary(**params)` | List glossary terms |
| `get_term(slug)` | Get glossary term detail |
| `list_guides(**params)` | List all guides |
| `get_guide(slug)` | Get guide detail |
| `list_guide_series(**params)` | List guide series |
| `get_guide_sery(slug)` | Get guide series detail |
| `list_faqs(**params)` | List all FAQs |
| `get_faq(slug)` | Get FAQ detail |
| `search(query)` | Search across all content |

Full API documentation at [boardgamefyi.com/developers/](https://boardgamefyi.com/developers/).

## Learn More About Board Games

- **Browse**: [Games](https://boardgamefyi.com/) · [Mechanics](https://boardgamefyi.com/) · [Designers](https://boardgamefyi.com/)
- **Guides**: [Glossary](https://boardgamefyi.com/glossary/) · [Guides](https://boardgamefyi.com/guides/)
- **API**: [REST API Docs](https://boardgamefyi.com/developers/) · [OpenAPI Spec](https://boardgamefyi.com/api/openapi.json)

## Guide FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem -- life reference guides, calculators, education, and games.

| Package | PyPI | Description |
|---------|------|-------------|
| calcfyi | [PyPI](https://pypi.org/project/calcfyi/) | 200+ calculators, financial, health, math -- [calcfyi.com](https://calcfyi.com/) |
| salaryfyi | [PyPI](https://pypi.org/project/salaryfyi/) | Salary comparison, tax calculators, 36 countries -- [salaryfyi.com](https://salaryfyi.com/) |
| univfyi | [PyPI](https://pypi.org/project/univfyi/) | University rankings, programs, admissions -- [univfyi.com](https://univfyi.com/) |
| **boardgamefyi** | [PyPI](https://pypi.org/project/boardgamefyi/) | **Board games, rules, reviews, recommendations -- [boardgamefyi.com](https://boardgamefyi.com/)** |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies -- [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata -- [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats -- [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings -- [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS -- [fontfyi.com](https://fontfyi.com/) |
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | [npm](https://www.npmjs.com/package/distancefyi) | Haversine distance & travel times -- [distancefyi.com](https://distancefyi.com/) |
| timefyi | [PyPI](https://pypi.org/project/timefyi/) | [npm](https://www.npmjs.com/package/timefyi) | Timezone ops & business hours -- [timefyi.com](https://timefyi.com/) |
| namefyi | [PyPI](https://pypi.org/project/namefyi/) | [npm](https://www.npmjs.com/package/namefyi) | Korean romanization & Five Elements -- [namefyi.com](https://namefyi.com/) |
| unitfyi | [PyPI](https://pypi.org/project/unitfyi/) | [npm](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units -- [unitfyi.com](https://unitfyi.com/) |
| holidayfyi | [PyPI](https://pypi.org/project/holidayfyi/) | [npm](https://www.npmjs.com/package/holidayfyi) | Holiday dates & Easter calculation -- [holidayfyi.com](https://holidayfyi.com/) |
| **boardgamefyi** | [PyPI](https://pypi.org/project/boardgamefyi/) | -- | **Board games, rules, reviews, recommendations -- [boardgamefyi.com](https://boardgamefyi.com/)** |
| cocktailfyi | [PyPI](https://pypi.org/project/cocktailfyi/) | -- | Cocktail ABV, calories, flavor -- [cocktailfyi.com](https://cocktailfyi.com/) |
| fyipedia | [PyPI](https://pypi.org/project/fyipedia/) | -- | Unified CLI for all FYI tools -- [fyipedia.com](https://fyipedia.com/) |

## License

MIT
