README.md
Manage your Lutris game library with AI assistance
lutris-mcp
MCP server for managing your Lutris game library. Gives AI assistants direct access to browse, search, organize, launch, and install games in your Linux gaming collection.
Examples
Here are some things you can ask your AI assistant once this server is connected:
- "What games do I have installed?"
- "Show me my most played games"
- "Search my Steam library for Hades"
- "Launch Balatro"
- "Install this game from
/path/to/setup.exe" - "Add all my roguelike games to a 'Roguelike' category"
- "Are there any duplicate games in my library?"
- "Show me the log for my last Hades II session"
- "Export my installed games as JSON"
- "Set the cover art for Timberborn from this image"
Installation
Quick Start (npx)
No install needed — just add to your MCP client config:
{
"mcpServers": {
"lutris": {
"command": "npx",
"args": ["-y", "lutris-mcp"]
}
}
}
Global Install
npm install -g lutris-mcp
Then configure your MCP client:
{
"mcpServers": {
"lutris": {
"command": "lutris-mcp"
}
}
}
From Source
git clone https://github.com/Praeses0/lutris-mcp.git
cd lutris-mcp
npm install
npm run build
{
"mcpServers": {
"lutris": {
"command": "node",
"args": ["/path/to/lutris-mcp/dist/index.js"]
}
}
}
Requirements
- Lutris installed and set up
- Node.js 20+
Tools
Library
| Tool | Description |
|---|---|
list_games |
List and filter games with pagination, sorting, and smart search |
get_game |
Get full game details including categories, config, and media paths |
add_game |
Add a new game to the library |
update_game |
Update fields on an existing game |
remove_game |
Remove a game from the database (does not delete files) |
get_library_stats |
Aggregate stats: totals, playtime, breakdowns by runner/platform/service |
find_duplicates |
Find potential duplicate games (same directory or similar slugs) |
export_library |
Export full library as JSON with optional filters (category, runner, installed) |
Categories
| Tool | Description |
|---|---|
list_categories |
List all categories with game counts |
create_category |
Create a new category |
assign_category |
Add a game to a category |
unassign_category |
Remove a game from a category |
bulk_assign_category |
Add multiple games to a category at once |
Services
| Tool | Description |
|---|---|
search_service_games |
Search games synced from Steam, GOG, etc. |
import_service_game |
Import a service game into your Lutris library |
Launch & Install
| Tool | Description |
|---|---|
launch_game |
Launch an installed game via Lutris |
install_game |
Install a game from a Lutris installer slug or local setup executable |
check_game_running |
Check if a game is currently running (multi-strategy detection) |
Configuration
| Tool | Description |
|---|---|
read_game_config |
Read a game's YAML configuration file |
write_game_config |
Update or create a game's YAML configuration (deep-merged) |
Media
| Tool | Description |
|---|---|
set_game_cover |
Set a game's cover art, banner, or icon from a local file |
get_game_media |
Get all media paths for a game with existence check |
System
| Tool | Description |
|---|---|
list_runners |
List available Lutris runners or Wine versions |
view_game_log |
Read the last launch log for a game (for troubleshooting) |
Bulk Operations
| Tool | Description |
|---|---|
bulk_update_games |
Update a field on multiple games at once |
Environment Variables
| Variable | Default | Description |
|---|---|---|
LUTRIS_DB_PATH |
~/.local/share/lutris/pga.db |
Path to Lutris SQLite database |
LUTRIS_GAMES_CONFIG_DIR |
~/.config/lutris/games |
Path to game YAML configs |
LUTRIS_DATA_DIR |
~/.local/share/lutris |
Path to Lutris data directory (media, logs) |
Development
npm install # install dependencies
npm run build # compile TypeScript
npm test # run tests (219 tests)
npm run dev # run with tsx (hot reload)
License
MIT
Tools (25)
list_gamesList and filter games with pagination, sorting, and smart searchget_gameGet full game details including categories, config, and media pathsadd_gameAdd a new game to the libraryupdate_gameUpdate fields on an existing gameremove_gameRemove a game from the databaseget_library_statsAggregate stats: totals, playtime, breakdowns by runner/platform/servicefind_duplicatesFind potential duplicate gamesexport_libraryExport full library as JSON with optional filterslist_categoriesList all categories with game countscreate_categoryCreate a new categoryassign_categoryAdd a game to a categoryunassign_categoryRemove a game from a categorybulk_assign_categoryAdd multiple games to a category at oncesearch_service_gamesSearch games synced from Steam, GOG, etc.import_service_gameImport a service game into your Lutris librarylaunch_gameLaunch an installed game via Lutrisinstall_gameInstall a game from a Lutris installer slug or local setup executablecheck_game_runningCheck if a game is currently runningread_game_configRead a game's YAML configuration filewrite_game_configUpdate or create a game's YAML configurationset_game_coverSet a game's cover art, banner, or icon from a local fileget_game_mediaGet all media paths for a game with existence checklist_runnersList available Lutris runners or Wine versionsview_game_logRead the last launch log for a gamebulk_update_gamesUpdate a field on multiple games at onceEnvironment Variables
LUTRIS_DB_PATHPath to Lutris SQLite databaseLUTRIS_GAMES_CONFIG_DIRPath to game YAML configsLUTRIS_DATA_DIRPath to Lutris data directoryConfiguration
claude_desktop_config.json
{"mcpServers": {"lutris": {"command": "npx", "args": ["-y", "lutris-mcp"]}}}Try it
→What games do I have installed?
→Show me my most played games
→Launch Balatro
→Add all my roguelike games to a 'Roguelike' category
→Show me the log for my last Hades II session