mirror of
https://github.com/gethomepage/homepage.git
synced 2026-10-02 17:01:15 -07:00
93 lines
2.8 KiB
Markdown
93 lines
2.8 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`. |
|
|
| `homepage_docs` | Returns focused Homepage documentation links for common setup topics. |
|
|
|
|
## 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"}'
|
|
```
|