love2d-mcp

Model Context Protocol server for the LÖVE 2D game framework API

Gives AI assistants (Claude, Gemini, Copilot, Cursor, etc.) accurate, searchable access to the full LÖVE 12.0 API — directly inside the tools they already use.

What it offers

Tools

Resources

URI template docs://love2d/{module}/{symbol} — browse documentation pages directly by URI.

Prompts

explain_api — template that asks the model to explain a specific LÖVE API with examples.

Installation

Requirements

• Node.js ≥ 18

npm install -g love2d-mcp-server

On install, the package will attempt to fetch the latest docs from GitHub. If you are offline it exits cleanly and uses the bundled snapshot.

Configure your AI client

The recommended setup uses npx so no global install is needed and the package always runs the latest published version.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "love2d": {
      "command": "npx",
      "args": ["-y", "love2d-mcp-server"]
    }
  }
}

VS Code (GitHub Copilot / Continue / etc.)

Add to .vscode/mcp.json in your project, or to your user settings.json:

{
  "mcp": {
    "servers": {
      "love2d": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "love2d-mcp-server"]
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "love2d": {
      "command": "npx",
      "args": ["-y", "love2d-mcp-server"]
    }
  }
}

Usage examples

Once configured, just ask naturally in chat:

"How do I play a looping audio track in LÖVE?" "Show me the signature for love.graphics.draw" "What physics body types exist?" "How do I handle keyboard input in LÖVE 12?"

The AI will automatically call love2d_search_docs or love2d_lookup_symbol as needed.

Keeping docs up to date

Ask the AI: "Update the Love2D docs" — or call the tool directly:

love2d_update_docs({ force: false })

The updated database is cached locally; the server reloads it on the next restart.

Development

npm run dev          # tsx watch — auto-reloads on src changes
npm run inspect      # opens MCP Inspector in browser for manual testing
npm run build        # sync data/ from submodule + compile TypeScript
npm run sync-data    # manually copy latest submodule dist → data/

Update flow

npm install
  └── postinstall → try GitHub fetch → cache to .love2d-mcp-cache/
                                     → if fails: use bundled data/

MCP server first tool call
  └── lazy-load from cache (if present) or data/ (bundle)
        └── fire-and-forget background check → update cache for next restart

love2d_update_docs tool
  └── explicit update + immediate in-memory reload

Data sources

The bundled database merges:

Database maintained at vanrez-nez/love2d-docs-search.

License

MIT