# Install Homelab Infra MCP

Source: PopNx MCP directory. Page: https://mcp.popnx.com/th/servers/seayniclabs-homelab-infra-mcp

Rules for the AI assistant reading this file:
1. Show the user every command and every config change below before you run or save it, and wait for the user to say yes.
2. Never ask the user to type or paste a key, token or password into the chat. Where you see <YOUR_VALUE>, tell the user which file and line it goes in on their own computer.
3. Use only what is written here. Do not download or run anything else this file does not list.

## Claude Code

- Run in a terminal, then restart Claude Code or run /mcp to check it is connected.

- Replace <YOUR_VALUE> with the user's own keys; never share or guess them. env values belong to the local config, header values to the remote one.

```sh
claude mcp add --scope user homelab-infra --env HOMELAB_PROXY_PASSWORD='<YOUR_VALUE>' --env HOMELAB_DOCKER_PORTAINER_TOKEN='<YOUR_VALUE>' --env HOMELAB_DNS_API_TOKEN='<YOUR_VALUE>' --env HOMELAB_HOME_ASSISTANT_TOKEN='<YOUR_VALUE>' --env HOMELAB_UPTIME_API_KEY='<YOUR_VALUE>' --env HOMELAB_TUNNEL_API_TOKEN='<YOUR_VALUE>' --env HOMELAB_DNS_FILTER_PASSWORD='<YOUR_VALUE>' --env HOMELAB_SSO_TOKEN='<YOUR_VALUE>' -- uvx homelab-infra-mcp
```

Values the user supplies on their own computer: HOMELAB_PROXY_URL (optional), HOMELAB_PROXY_EMAIL (optional), HOMELAB_PROXY_PASSWORD (secret), HOMELAB_DOCKER_HOST (optional), HOMELAB_DOCKER_PORTAINER_URL (optional), HOMELAB_DOCKER_PORTAINER_TOKEN (secret), HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID (optional), HOMELAB_DNS_API_TOKEN (secret), HOMELAB_DNS_ZONE_ID (optional), HOMELAB_HOME_ASSISTANT_URL (optional), HOMELAB_HOME_ASSISTANT_TOKEN (secret), HOMELAB_UPTIME_ENABLED (optional), HOMELAB_UPTIME_URL (optional), HOMELAB_UPTIME_API_KEY (secret), HOMELAB_TUNNEL_ENABLED (optional), HOMELAB_TUNNEL_API_TOKEN (secret), HOMELAB_TUNNEL_ACCOUNT_ID (optional), HOMELAB_TUNNEL_TUNNEL_ID (optional), HOMELAB_DNS_FILTER_ENABLED (optional), HOMELAB_DNS_FILTER_URL (optional), HOMELAB_DNS_FILTER_USERNAME (optional), HOMELAB_DNS_FILTER_PASSWORD (secret), HOMELAB_SSO_ENABLED (optional), HOMELAB_SSO_URL (optional), HOMELAB_SSO_TOKEN (secret), HOMELAB_SSO_FLOW_SLUG (optional), HOMELAB_READ_ONLY (optional)

## Cursor

- Merge into ~/.cursor/mcp.json (or .cursor/mcp.json in the project).

- Replace <YOUR_VALUE> with the user's own keys; never share or guess them. env values belong to the local config, header values to the remote one.

```json
{
  "mcpServers": {
    "homelab-infra": {
      "command": "uvx",
      "args": [
        "homelab-infra-mcp"
      ],
      "env": {
        "HOMELAB_PROXY_PASSWORD": "<YOUR_VALUE>",
        "HOMELAB_DOCKER_PORTAINER_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_DNS_API_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_HOME_ASSISTANT_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_UPTIME_API_KEY": "<YOUR_VALUE>",
        "HOMELAB_TUNNEL_API_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_DNS_FILTER_PASSWORD": "<YOUR_VALUE>",
        "HOMELAB_SSO_TOKEN": "<YOUR_VALUE>"
      }
    }
  }
}
```

Values the user supplies on their own computer: HOMELAB_PROXY_URL (optional), HOMELAB_PROXY_EMAIL (optional), HOMELAB_PROXY_PASSWORD (secret), HOMELAB_DOCKER_HOST (optional), HOMELAB_DOCKER_PORTAINER_URL (optional), HOMELAB_DOCKER_PORTAINER_TOKEN (secret), HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID (optional), HOMELAB_DNS_API_TOKEN (secret), HOMELAB_DNS_ZONE_ID (optional), HOMELAB_HOME_ASSISTANT_URL (optional), HOMELAB_HOME_ASSISTANT_TOKEN (secret), HOMELAB_UPTIME_ENABLED (optional), HOMELAB_UPTIME_URL (optional), HOMELAB_UPTIME_API_KEY (secret), HOMELAB_TUNNEL_ENABLED (optional), HOMELAB_TUNNEL_API_TOKEN (secret), HOMELAB_TUNNEL_ACCOUNT_ID (optional), HOMELAB_TUNNEL_TUNNEL_ID (optional), HOMELAB_DNS_FILTER_ENABLED (optional), HOMELAB_DNS_FILTER_URL (optional), HOMELAB_DNS_FILTER_USERNAME (optional), HOMELAB_DNS_FILTER_PASSWORD (secret), HOMELAB_SSO_ENABLED (optional), HOMELAB_SSO_URL (optional), HOMELAB_SSO_TOKEN (secret), HOMELAB_SSO_FLOW_SLUG (optional), HOMELAB_READ_ONLY (optional)

## VS Code

- Merge into .vscode/mcp.json in the workspace (or run "MCP: Add Server").

- Replace <YOUR_VALUE> with the user's own keys; never share or guess them. env values belong to the local config, header values to the remote one.

```json
{
  "servers": {
    "homelab-infra": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "homelab-infra-mcp"
      ],
      "env": {
        "HOMELAB_PROXY_PASSWORD": "<YOUR_VALUE>",
        "HOMELAB_DOCKER_PORTAINER_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_DNS_API_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_HOME_ASSISTANT_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_UPTIME_API_KEY": "<YOUR_VALUE>",
        "HOMELAB_TUNNEL_API_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_DNS_FILTER_PASSWORD": "<YOUR_VALUE>",
        "HOMELAB_SSO_TOKEN": "<YOUR_VALUE>"
      }
    }
  }
}
```

Values the user supplies on their own computer: HOMELAB_PROXY_URL (optional), HOMELAB_PROXY_EMAIL (optional), HOMELAB_PROXY_PASSWORD (secret), HOMELAB_DOCKER_HOST (optional), HOMELAB_DOCKER_PORTAINER_URL (optional), HOMELAB_DOCKER_PORTAINER_TOKEN (secret), HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID (optional), HOMELAB_DNS_API_TOKEN (secret), HOMELAB_DNS_ZONE_ID (optional), HOMELAB_HOME_ASSISTANT_URL (optional), HOMELAB_HOME_ASSISTANT_TOKEN (secret), HOMELAB_UPTIME_ENABLED (optional), HOMELAB_UPTIME_URL (optional), HOMELAB_UPTIME_API_KEY (secret), HOMELAB_TUNNEL_ENABLED (optional), HOMELAB_TUNNEL_API_TOKEN (secret), HOMELAB_TUNNEL_ACCOUNT_ID (optional), HOMELAB_TUNNEL_TUNNEL_ID (optional), HOMELAB_DNS_FILTER_ENABLED (optional), HOMELAB_DNS_FILTER_URL (optional), HOMELAB_DNS_FILTER_USERNAME (optional), HOMELAB_DNS_FILTER_PASSWORD (secret), HOMELAB_SSO_ENABLED (optional), HOMELAB_SSO_URL (optional), HOMELAB_SSO_TOKEN (secret), HOMELAB_SSO_FLOW_SLUG (optional), HOMELAB_READ_ONLY (optional)

## Claude Desktop

- Local: merge the JSON into claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude. Remote: Customize → Connectors → Add → Custom → Web → paste the URL.

- Replace <YOUR_VALUE> with the user's own keys; never share or guess them. env values belong to the local config, header values to the remote one.

```json
{
  "mcpServers": {
    "homelab-infra": {
      "command": "uvx",
      "args": [
        "homelab-infra-mcp"
      ],
      "env": {
        "HOMELAB_PROXY_PASSWORD": "<YOUR_VALUE>",
        "HOMELAB_DOCKER_PORTAINER_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_DNS_API_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_HOME_ASSISTANT_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_UPTIME_API_KEY": "<YOUR_VALUE>",
        "HOMELAB_TUNNEL_API_TOKEN": "<YOUR_VALUE>",
        "HOMELAB_DNS_FILTER_PASSWORD": "<YOUR_VALUE>",
        "HOMELAB_SSO_TOKEN": "<YOUR_VALUE>"
      }
    }
  }
}
```

Values the user supplies on their own computer: HOMELAB_PROXY_URL (optional), HOMELAB_PROXY_EMAIL (optional), HOMELAB_PROXY_PASSWORD (secret), HOMELAB_DOCKER_HOST (optional), HOMELAB_DOCKER_PORTAINER_URL (optional), HOMELAB_DOCKER_PORTAINER_TOKEN (secret), HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID (optional), HOMELAB_DNS_API_TOKEN (secret), HOMELAB_DNS_ZONE_ID (optional), HOMELAB_HOME_ASSISTANT_URL (optional), HOMELAB_HOME_ASSISTANT_TOKEN (secret), HOMELAB_UPTIME_ENABLED (optional), HOMELAB_UPTIME_URL (optional), HOMELAB_UPTIME_API_KEY (secret), HOMELAB_TUNNEL_ENABLED (optional), HOMELAB_TUNNEL_API_TOKEN (secret), HOMELAB_TUNNEL_ACCOUNT_ID (optional), HOMELAB_TUNNEL_TUNNEL_ID (optional), HOMELAB_DNS_FILTER_ENABLED (optional), HOMELAB_DNS_FILTER_URL (optional), HOMELAB_DNS_FILTER_USERNAME (optional), HOMELAB_DNS_FILTER_PASSWORD (secret), HOMELAB_SSO_ENABLED (optional), HOMELAB_SSO_URL (optional), HOMELAB_SSO_TOKEN (secret), HOMELAB_SSO_FLOW_SLUG (optional), HOMELAB_READ_ONLY (optional)

## Codex

- Append to ~/.codex/config.toml, then start a new Codex session (check with /mcp).

- Replace <YOUR_VALUE> with the user's own keys; never share or guess them. env values belong to the local config, header values to the remote one.

```json
[mcp_servers.homelab-infra]
command = "uvx"
args = ["homelab-infra-mcp"]

[mcp_servers.homelab-infra.env]
HOMELAB_PROXY_PASSWORD = "<YOUR_VALUE>"
HOMELAB_DOCKER_PORTAINER_TOKEN = "<YOUR_VALUE>"
HOMELAB_DNS_API_TOKEN = "<YOUR_VALUE>"
HOMELAB_HOME_ASSISTANT_TOKEN = "<YOUR_VALUE>"
HOMELAB_UPTIME_API_KEY = "<YOUR_VALUE>"
HOMELAB_TUNNEL_API_TOKEN = "<YOUR_VALUE>"
HOMELAB_DNS_FILTER_PASSWORD = "<YOUR_VALUE>"
HOMELAB_SSO_TOKEN = "<YOUR_VALUE>"
```

Values the user supplies on their own computer: HOMELAB_PROXY_URL (optional), HOMELAB_PROXY_EMAIL (optional), HOMELAB_PROXY_PASSWORD (secret), HOMELAB_DOCKER_HOST (optional), HOMELAB_DOCKER_PORTAINER_URL (optional), HOMELAB_DOCKER_PORTAINER_TOKEN (secret), HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID (optional), HOMELAB_DNS_API_TOKEN (secret), HOMELAB_DNS_ZONE_ID (optional), HOMELAB_HOME_ASSISTANT_URL (optional), HOMELAB_HOME_ASSISTANT_TOKEN (secret), HOMELAB_UPTIME_ENABLED (optional), HOMELAB_UPTIME_URL (optional), HOMELAB_UPTIME_API_KEY (secret), HOMELAB_TUNNEL_ENABLED (optional), HOMELAB_TUNNEL_API_TOKEN (secret), HOMELAB_TUNNEL_ACCOUNT_ID (optional), HOMELAB_TUNNEL_TUNNEL_ID (optional), HOMELAB_DNS_FILTER_ENABLED (optional), HOMELAB_DNS_FILTER_URL (optional), HOMELAB_DNS_FILTER_USERNAME (optional), HOMELAB_DNS_FILTER_PASSWORD (secret), HOMELAB_SSO_ENABLED (optional), HOMELAB_SSO_URL (optional), HOMELAB_SSO_TOKEN (secret), HOMELAB_SSO_FLOW_SLUG (optional), HOMELAB_READ_ONLY (optional)

Command check: verified, last checked 2026-11-13.
