mirror of
https://github.com/gethomepage/homepage.git
synced 2026-10-03 01:11:17 -07:00
128 lines
3.7 KiB
Markdown
128 lines
3.7 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.
|
|
|
|
## 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
|
|
|
|
If `HOMEPAGE_MCP_TOKEN` is set, MCP requests must 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_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:
|
|
|
|
```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. |
|
|
|
|
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:
|
|
|
|
```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"}'
|
|
```
|