mirror of
https://github.com/gethomepage/homepage.git
synced 2026-09-12 15:15:58 -07:00
shamoon
152 lines
5.2 KiB
Markdown
152 lines
5.2 KiB
Markdown
---
|
|
title: Model Context Protocol
|
|
---
|
|
|
|
Homepage includes an optional, lightweight [Model Context Protocol](https://modelcontextprotocol.io/) 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:
|
|
|
|
```yaml
|
|
HOMEPAGE_MCP_ENABLED: "true"
|
|
```
|
|
|
|
The endpoint is available at:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
Authorization: Bearer your-token
|
|
```
|
|
|
|
or:
|
|
|
|
```txt
|
|
X-Homepage-MCP-Token: your-token
|
|
```
|
|
|
|
Example Docker Compose environment block:
|
|
|
|
```yaml
|
|
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`](https://www.npmjs.com/package/mcp-remote) to communicate with the homepage MCP endpoint in `claude_desktop_config.json`:
|
|
|
|
```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:
|
|
|
|
```yaml
|
|
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. |
|
|
|
|
For example, an assistant can add a service with:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```txt
|
|
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
|
|
|
|
```bash
|
|
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"}'
|
|
```
|