homepage/docs/configs/mcp.md

title

title
Model Context Protocol

Homepage includes an optional, lightweight Model Context Protocol endpoint that can help AI assistants inspect, validate, and, if you explicitly allow it, update Homepage configuration files.

This endpoint is disabled by default. Do not expose it to an untrusted network unless you put Homepage behind authentication, TLS, and a reverse proxy that validates Host headers.

Enable the MCP endpoint

Set the following environment variable and restart Homepage:

HOMEPAGE_MCP_ENABLED: "true"

The endpoint is available at:

http://your-homepage-instance/api/mcp

Authentication

If HOMEPAGE_MCP_TOKEN is set, MCP requests must include either of the following headers:

Authorization: Bearer your-token

or:

X-Homepage-MCP-Token: your-token

Example Docker Compose environment block:

environment:
  HOMEPAGE_MCP_ENABLED: "true"
  HOMEPAGE_MCP_TOKEN: "change-me"

Read-only by default

The MCP endpoint exposes tools for reading and validating supported Homepage config files. File writes are disabled unless you opt in with:

HOMEPAGE_MCP_ALLOW_WRITE: "true"

When writes are enabled, YAML files are parsed before they are saved so a syntactically invalid YAML document is rejected instead of replacing the current file.

Supported tools

Tool	Description
list_config_files	Lists supported config files, whether they exist, and links to the related docs.
read_config_file	Reads one supported config file from HOMEPAGE_CONFIG_DIR.
validate_config_file	Validates YAML from a file or supplied content and returns line and column details for syntax errors.
write_config_file	Replaces a supported config file when HOMEPAGE_MCP_ALLOW_WRITE=true.
add_service	Appends a service to a group in services.yaml when HOMEPAGE_MCP_ALLOW_WRITE=true.
add_info_widget	Appends an information widget to widgets.yaml when HOMEPAGE_MCP_ALLOW_WRITE=true.
homepage_docs	Returns focused Homepage documentation links for common setup topics.

The structured write tools are safer than replacing an entire file because they parse the existing YAML, preserve the expected top-level structure, and only append a Homepage-shaped entry. For example, an assistant can add a service with:

{
  "group": "Media",
  "name": "Plex",
  "service": {
    "href": "https://plex.example.com",
    "icon": "plex.png",
    "description": "Movies and TV",
    "widget": {
      "type": "plex",
      "url": "https://plex.example.com",
      "key": "your-api-key"
    }
  }
}

Or add an info widget with:

{
  "type": "openmeteo",
  "options": {
    "label": "Current",
    "latitude": 36.66,
    "longitude": -117.51,
    "cache": 5
  }
}

Supported resources

The MCP server also exposes config files as MCP resources using this URI format:

homepage://config/services.yaml

Supported files are:

• settings.yaml
• services.yaml
• bookmarks.yaml
• widgets.yaml
• docker.yaml
• kubernetes.yaml
• proxmox.yaml
• custom.css
• custom.js

Example request

curl -s http://localhost:3000/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-token' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'