LÖVE2D MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with running LÖVE2D games. This allows for real-time introspection, debugging, and manipulation of game state through natural language.

Overview

This project bridges LÖVE2D games with MCP-compatible AI assistants, enabling:

• Real-time introspection: Query game objects, positions, properties, and state
• Dynamic code execution: Run Lua code directly in the game context
• AI-assisted debugging: Let AI assistants analyze and manipulate your game
• Interactive development: Modify game behavior without restarting

Architecture

┌─────────────┐ stdio  ┌─────────────┐  TCP   ┌─────────────┐
│ MCP Client  │◄──────►│  MCP Server │◄──────►│  LÖVE2D     │
│ (Inspector) │        │ (TypeScript)│        │  Game (Lua) │
└─────────────┘        └─────────────┘        └─────────────┘

• MCP Server: Node.js/TypeScript server communicating via stdio
• LÖVE2D Bridge: Lua TCP server embedded in your game
• Communication: JSON-RPC over TCP between server and game

Installation

Prerequisites

• Node.js 18+ and npm
• LÖVE2D 11.0+ (download here)
• Git

Setup

1. Clone the repository:

git clone https://github.com/shayarnett/love2d-mcp.git
cd love2d-mcp

2. Install dependencies:

npm install

3. Build the TypeScript server:

npm run build

Quick Start

1. Start the Example Game

love game/

You should see a window with 5 bouncing balls. The game starts a TCP server on port 12345.

2. Connect with MCP Inspector

In a new terminal:

npx @modelcontextprotocol/inspector node build/index.js

This opens the MCP Inspector in your browser where you can interact with the game.

3. Try Some Commands

List all objects:

• Select the list_objects tool
• Execute it to see all game objects

Get object details:

• Select the get_object tool
• Enter an object ID from the list (e.g., ball_1)
• View detailed properties

Run custom Lua code:

• Select the run_lua tool
• Try this code to count purple balls:

local count = 0
for id, obj in pairs(objects) do
  if obj.type == "ball" then
    if obj.b > 0.5 and obj.r > 0.5 and obj.g < 0.5 then
      count = count + 1
    end
  end
end
return count

Available MCP Tools

list_objects

Lists all objects in the current game scene.

Parameters: None

Returns: Array of objects with id, type, x, and y properties.

get_object

Get detailed information about a specific object.

Parameters:

• id (string): The object ID

Returns: Complete object data including all properties.

run_lua

Execute arbitrary Lua code in the game context with access to game objects.

Parameters:

• code (string): Lua code to execute

Returns: Result of the code execution (string or JSON-encoded table).

Available in code context: