boardgamefyi 0.1.1

Board games, rules and reviews API client — boardgamefyi.com

boardgamefyi

Python API client for 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 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 -- browse games, compare mechanics, and discover game night themes.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Browse Games and Mechanics
  • Designers, Artists, and Publishers
  • Game Night Themes and Progression Paths
  • Awards and Recognition
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About Board Games
• Guide FYI Family
• FYIPedia Developer Tools
• License

Install

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

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

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 · Glossary · 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

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 · Publishers · API Docs

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

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 · Progression Paths · 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

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 · FAQs · Glossary

Command-Line Interface

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.

pip install "boardgamefyi[mcp]"

Add to your claude_desktop_config.json:

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

Available tools: search_boardgamefyi

REST API Client

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/.

Learn More About Board Games

• Browse: Games · Mechanics · Designers
• Guides: Glossary · Guides
• API: REST API Docs · OpenAPI Spec

Guide FYI Family

Part of the FYIPedia open-source developer tools ecosystem -- life reference guides, calculators, education, and games.

Package	PyPI	Description
calcfyi	PyPI	200+ calculators, financial, health, math -- calcfyi.com
salaryfyi	PyPI	Salary comparison, tax calculators, 36 countries -- salaryfyi.com
univfyi	PyPI	University rankings, programs, admissions -- univfyi.com
boardgamefyi	PyPI	Board games, rules, reviews, recommendations -- boardgamefyi.com

FYIPedia Developer Tools

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

License

MIT