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.

Once enabled you can use the endpoint to help an assistant understand your current Homepage configuration, add new services or widgets, and get links to relevant documentation. For example, an assistant could add a new media service to your dashboard by appending it to services.yaml via the MCP endpoint instead of you having to manually edit the file. For example, you can ask an assistant to add a new service entry for Paperless-ngx:

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#

The MCP endpoint requires authentication. Requests from an authenticated Homepage session are allowed when Homepage auth is enabled with HOMEPAGE_AUTH_ENABLED.

For MCP clients that cannot use the browser session, set HOMEPAGE_MCP_TOKEN. An MCP token is required when Homepage auth is not enabled. The token grants read access to every configured service credential and, with writes enabled, control of custom.js (which runs in every browser), so it must be at least 32 characters — generate one with openssl rand -base64 32. Homepage refuses MCP requests while a shorter token is configured. Requests can 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_AUTH_ENABLED: "true"
  HOMEPAGE_MCP_TOKEN: "generate-with-openssl-rand-base64-32"

Connecting Claude Desktop#

Claude Desktop can use mcp-remote to communicate with the homepage MCP endpoint in claude_desktop_config.json:

{
  "mcpServers": {
    "homepage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp", "--header", "X-Homepage-MCP-Token: your-token"]
    }
  }
}

The Add custom connector option will not work: remote connectors authenticate with OAuth and cannot supply HOMEPAGE_MCP_TOKEN.

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#

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"}'