Wallpaper

Generates AI wallpaper images and applies them as macOS desktop wallpaper via MCP clients.

python

3

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "shahanneda-wallpaper-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "lumaai",
        "--with",
        "requests",
        "mcp",
        "run",
        "/path/to/server.py"
      ],
      "env": {
        "LUMAAI_API_KEY": "API_KEY_HERE"
      }
    }
  }
}

Wallpaper MCP lets MCP clients generate AI-based wallpaper images and apply them as your macOS desktop wallpaper. It provides simple actions to produce, store, and set wallpapers from prompts, enabling automated or on-demand customization of your desktop appearance.

How to use

You can generate a wallpaper from a prompt, save it to a file, and set it as your macOS desktop wallpaper using a single workflow. Start with a prompt that describes the scene, color palette, and mood you want. Then choose one of the available actions: generate a wallpaper image, save it to a temporary path, or immediately generate and apply it as your wallpaper. If you already have an image, you can set the wallpaper directly from its file path.

How to install

Prerequisites you need before installation are macOS and a Luma Labs API key.

Install steps you follow locally are below. Use the exact commands and code blocks as shown.

git clone git@github.com:shahanneda/wallpaper-mcp.git
cd wallpaper-mcp

# Obtain and configure your Luma Labs API key as described in your setup steps.

Additional configuration and testing

To integrate with Claude Desktop, you can add a macOS-specific configuration that runs the MCP server through a local command. The following example configures the wallpaper server to start via a local MPC runtime and includes your LUMAAI API key.

{
  "wallpaper": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli]",
      "--with",
      "lumaai",
      "--with",
      "requests",
      "mcp",
      "run",
      "/path/to/server.py"
    ],
    "env": {
      "LUMAAI_API_KEY": "API_KEY_HERE"
    }
  }
}

Testing with MCP Inspector

You can test the server using a dev command that runs the MCP server locally with the required integrations.

LUMAAI_API_KEY=API_KEY_HERE mcp dev server.py --with lumaai --with requests

Available tools

generate_image

Generates an image using Luma Labs AI from a text prompt and returns the generated image.

generate_wallpaper

Generates a wallpaper image from a prompt and saves it to a temporary directory, returning the path to the image.

set_image_from_path

Sets the wallpaper using an image file from a specified path and returns a success/failure message.

generate_and_set_wallpaper

Generates a wallpaper from a prompt and immediately applies it as the desktop wallpaper, returning a status message.