### Install Development Dependencies

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/CONTRIBUTING.md

Installs all development dependencies, including extras, using uv.

```bash
uv sync --all-extras --dev
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Install pre-commit hooks for the project.

```bash
uv run pre-commit install
```

--------------------------------

### Install homarr-mcp

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Clone the repository and install dependencies using uv.

```bash
git clone https://github.com/TETRA-2023/homarr-mcp.git
cd homarr-mcp
uv sync
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/CLAUDE.md

Copies the example environment file to '.env'. You must then configure HOMARR_URL and HOMARR_API_KEY within this file.

```bash
cp .env.example .env
```

--------------------------------

### Configure homarr-mcp

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Copy the example environment file and edit it with your Homarr URL and API key.

```bash
cp .env.example .env
# Edit .env with your Homarr URL and API key
```

--------------------------------

### Run homarr-mcp with stdio

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Start the MCP server using the stdio transport, suitable for local execution with Claude Code.

```bash
uv run python src/server.py
```

--------------------------------

### Run homarr-mcp with streamable-http

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Start the MCP server using the streamable-http transport, recommended for Docker or remote access.

```bash
uv run python src/server.py --streamable-http
```

--------------------------------

### List Boards with Verbosity (Python)

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Example of using the `list_boards` server function with different verbosity levels to control the returned fields. Assumes the client is initialized.

```python
import asyncio
import src.server as server
from unittest.mock import AsyncMock
from src.homarr_client import HomarrClient

async def example():
    # In real usage the client is initialized via server lifespan.
    # For demonstration, inject a real client:
    server._client = HomarrClient("http://localhost:7575", "abc123.token")

    boards = await server.list_boards(verbosity="standard")
    # [
    #   {"id": "clx1", "name": "Home", "isPublic": True, "logoImageUrl": None, ...},
    #   {"id": "clx2", "name": "Media", "isPublic": False, ...}
    # ]

    boards_minimal = await server.list_boards(verbosity="minimal")
    # [{"id": "clx1", "name": "Home", "isPublic": True}]

    await server._client.close()

asyncio.run(example())
```

--------------------------------

### Get Board Details

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Fetches a single board with full layout details. Use `list_boards` first to discover board names.

```python
async def example():
    board = await server.get_board("Home", verbosity="standard")
    # {
    #   "id": "clx1",
    #   "name": "Home",
    #   "isPublic": True,
    #   "sections": [{"id": "sec1", "type": "empty", "position": 0}],
    #   "items": [{"id": "item1", "kind": "app", "appId": "app1", ...}],
    #   "layouts": [{"id": "lay1", "name": "default"}],
    #   "primaryColor": "#fa5252",
    #   "secondaryColor": "#be4bdb"
    # }
```

--------------------------------

### Get a group by ID

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Fetches a single group, including its members and permissions. Use 'full' verbosity for complete details.

```python
async def example():
    group = await server.get_group("g1", verbosity="full")
    # {
    #   "id": "g1",
    #   "name": "Admins",
    #   "ownerId": "u1",
    #   "members": [{"id": "u1", "name": "Alice", "email": "alice@example.com"}],
    #   "permissions": [{"permission": "admin"}]
    # }
```

--------------------------------

### Get Single App by ID

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Fetches the complete record for a single app using its ID. Use `list_apps` to find available app IDs.

```python
async def example():
    app = await server.get_app("app1", verbosity="full")
    # {
    #   "id": "app1",
    #   "name": "Plex",
    #   "href": "https://plex.tv",
    #   "description": "Media server",
    #   "iconUrl": "https://cdn.example.com/plex.svg",
    #   "pingUrl": "https://plex.tv/health"
    # }
```

--------------------------------

### Create New App or Bookmark

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Creates a new app tile. `name` and `href` are mandatory. `icon_url` must be a valid URL.

```python
async def example():
    result = await server.create_app(
        name="Jellyfin",
        href="http://jellyfin:8096",
        description="Media server",
        icon_url="https://cdn.jsdelivr.net/npm/@homarr/icons@latest/svgs/jellyfin.svg",
        ping_url="http://jellyfin:8096/health",
    )
    print(result)  # {"id": "clxnewapp", "name": "Jellyfin", ...}

    # Minimal — uses default icon
    result = await server.create_app("Portainer", "http://portainer:9000")
```

--------------------------------

### List All Apps and Bookmarks

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Returns all registered app tiles. `standard` verbosity includes detailed information like ID, name, description, and URLs.

```python
async def example():
    apps = await server.list_apps(verbosity="standard")
    # [
    #   {"id": "app1", "name": "Plex", "href": "https://plex.tv", "pingUrl": "https://plex.tv/health"},
    #   {"id": "app2", "name": "Sonarr", "href": "http://sonarr:8989", "pingUrl": None}
    # ]

    apps_minimal = await server.list_apps(verbosity="minimal")
    # [{"id": "app1", "name": "Plex", "href": "https://plex.tv"}]
```

--------------------------------

### create_app

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Creates a new app tile or bookmark.

```APIDOC
## create_app

### Description
Creates an app tile. `name` and `href` are required. `icon_url` must be a non-empty URL (defaults to the Homarr default SVG icon).

### Method
POST

### Endpoint
/apps

### Parameters
#### Request Body
- **name** (string) - Required - The name of the app.
- **href** (string) - Required - The URL to access the app.
- **description** (string) - Optional - The description of the app.
- **icon_url** (string) - Optional - The URL of the app's icon. Defaults to the Homarr default SVG icon.
- **ping_url** (string) - Optional - The URL to ping for the app's status.

### Request Example
```python
await server.create_app(
    name="Jellyfin",
    href="http://jellyfin:8096",
    description="Media server",
    icon_url="https://cdn.jsdelivr.net/npm/@homarr/icons@latest/svgs/jellyfin.svg",
    ping_url="http://jellyfin:8096/health"
)

# Minimal creation
await server.create_app("Portainer", "http://portainer:9000")
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created app.
- **name** (string) - The name of the app.
- **href** (string) - The URL to access the app.
- **description** (string) - The description of the app.
- **iconUrl** (string) - The URL of the app's icon.
- **pingUrl** (string) - The URL to ping for the app's status.

### Response Example
```json
{
  "id": "clxnewapp",
  "name": "Jellyfin",
  "href": "http://jellyfin:8096",
  "description": "Media server",
  "iconUrl": "https://cdn.jsdelivr.net/npm/@homarr/icons@latest/svgs/jellyfin.svg",
  "pingUrl": "http://jellyfin:8096/health"
}
```
```

--------------------------------

### HomarrClient Basic Usage (Python)

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Demonstrates initializing and using the async HomarrClient for basic operations like checking connection, direct tRPC queries/mutations, and error handling.

```python
import asyncio
from src.homarr_client import HomarrClient, HomarrAPIError

async def main():
    client = HomarrClient(
        base_url="http://localhost:7575",
        api_key="abc123.secrettoken",
    )

    # Verify connectivity
    ok = await client.check_connection()
    print(ok)  # True

    # Direct tRPC query
    boards = await client._query("board.getAllBoards")

    # Direct tRPC mutation
    result = await client._mutate("board.createBoard", {
        "name": "My Board",
        "columnCount": 12,
        "isPublic": False,
    })
    print(result)  # {"boardId": "clxyz123"}

    # Error handling
    try:
        await client.get_board("nonexistent")
    except HomarrAPIError as e:
        print(e.status_code, str(e))  # 404 "Not found"

    await client.close()

asyncio.run(main())
```

--------------------------------

### Build and Run homarr-mcp Docker Image

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Build a Docker image for homarr-mcp and run it using environment variables from a .env file.

```bash
docker build -t homarr-mcp .
docker run --env-file .env homarr-mcp --streamable-http
```

--------------------------------

### Running Homarr MCP Server

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Command-line instructions for running the Homarr MCP server with different transport modes (stdio, SSE, streamable-http) and Docker.

```bash
# stdio — for Claude Code / local MCP clients (default)
uv run python src/server.py

# SSE transport
uv run python src/server.py --sse

# Streamable HTTP transport (Docker / remote)
uv run python src/server.py --streamable-http

# Docker
docker build -t homarr-mcp .
docker run --env-file .env -p 8000:8000 homarr-mcp --streamable-http
```

--------------------------------

### list_apps

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Returns all app tiles and bookmarks registered in Homarr.

```APIDOC
## list_apps

### Description
Returns all app tiles registered in Homarr. `standard` verbosity includes `id`, `name`, `description`, `iconUrl`, `href`, `pingUrl`.

### Method
GET

### Endpoint
/apps

### Parameters
#### Query Parameters
- **verbosity** (string) - Optional - The level of detail to return. Allowed values: "standard", "minimal". Defaults to "standard".

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the app.
- **name** (string) - The name of the app.
- **description** (string) - The description of the app.
- **iconUrl** (string) - The URL of the app's icon.
- **href** (string) - The URL to access the app.
- **pingUrl** (string) - The URL to ping for the app's status.

### Request Example
```python
apps = await server.list_apps(verbosity="standard")
apps_minimal = await server.list_apps(verbosity="minimal")
```

### Response Example
```json
[
  {"id": "app1", "name": "Plex", "href": "https://plex.tv", "pingUrl": "https://plex.tv/health"},
  {"id": "app2", "name": "Sonarr", "href": "http://sonarr:8989", "pingUrl": null}
]
```
```

--------------------------------

### create_board

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Creates a board with optional column count and visibility. Returns the new board's ID.

```APIDOC
## create_board

### Description
Creates a new board with optional column count (default 10) and visibility (default private). Returns `{"boardId": "<new-id>"}`.

### Method
POST

### Endpoint
/boards

### Parameters
#### Request Body
- **name** (string) - Required - The name for the new board.
- **column_count** (integer) - Optional - The number of columns for the board. Defaults to 10.
- **is_public** (boolean) - Optional - Whether the board should be public. Defaults to false.

### Request Example
```python
await server.create_board("DevOps", column_count=16, is_public=False)
```

### Response
#### Success Response (201)
- **boardId** (string) - The ID of the newly created board.

### Response Example
```json
{"boardId": "clxnewboard"}
```
```

--------------------------------

### Create New Board

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Creates a new board with optional column count and visibility. Returns the new board's ID.

```python
async def example():
    result = await server.create_board("DevOps", column_count=16, is_public=False)
    print(result)  # {"boardId": "clxnewboard"}

    # Minimal creation
    result = await server.create_board("Quick")
    # {"boardId": "clxquick"}
```

--------------------------------

### List all users

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Returns all users in the Homarr instance. 'standard' verbosity includes id, name, email, emailVerified, and image.

```python
async def example():
    users = await server.list_users(verbosity="standard")
    # [
    #   {"id": "u1", "name": "Alice", "email": "alice@example.com", "emailVerified": True, "image": None},
    #   {"id": "u2", "name": "Bob",   "email": "bob@example.com",   "emailVerified": False, "image": None}
    # ]
```

--------------------------------

### get_board

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Fetches a single board including sections, items, and layouts. Use `list_boards` first to discover board names.

```APIDOC
## get_board

### Description
Fetches a single board including sections, items, and layouts. Use `list_boards` first to discover board names.

### Method
GET

### Endpoint
/boards/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the board to retrieve.
- **verbosity** (string) - Optional - The level of detail to return. Allowed values: "standard", "full". Defaults to "standard".

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the board.
- **name** (string) - The name of the board.
- **isPublic** (boolean) - Indicates if the board is public.
- **sections** (array) - An array of section objects.
- **items** (array) - An array of item objects.
- **layouts** (array) - An array of layout objects.
- **primaryColor** (string) - The primary color of the board.
- **secondaryColor** (string) - The secondary color of the board.

### Request Example
```python
await server.get_board("Home", verbosity="standard")
```

### Response Example
```json
{
  "id": "clx1",
  "name": "Home",
  "isPublic": True,
  "sections": [{"id": "sec1", "type": "empty", "position": 0}],
  "items": [{"id": "item1", "kind": "app", "appId": "app1", ...}],
  "layouts": [{"id": "lay1", "name": "default"}],
  "primaryColor": "#fa5252",
  "secondaryColor": "#be4bdb"
}
```
```

--------------------------------

### Format Code with Ruff

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Check code formatting using ruff format --check.

```bash
uv run ruff format --check src/ tests/
```

--------------------------------

### List all groups with members

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Returns all groups, including their members. The 'standard' verbosity level includes id, name, ownerId, homeBoardId, mobileHomeBoardId, and members.

```python
async def example():
    groups = await server.list_groups(verbosity="standard")
    # [
    #   {
    #     "id": "g1", "name": "Admins", "ownerId": "u1",
    #     "homeBoardId": "clx1", "mobileHomeBoardId": None,
    #     "members": [{"id": "u1", "name": "Alice"}]
    #   }
    # ]
```

--------------------------------

### Homarr MCP Configuration (.env)

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Environment variables for configuring the Homarr MCP server, including Homarr instance URL, API key, and transport mode.

```bash
# .env
HOMARR_URL=http://localhost:7575          # Homarr instance base URL
HOMARR_API_KEY=abc123.secrettoken        # Created in Management > Tools > API Keys
HOMARR_TRANSPORT=stdio                   # stdio | sse | streamable-http
MCP_HOST=127.0.0.1                       # Host for HTTP transport (default 127.0.0.1)
MCP_PORT=8000                            # Port for HTTP transport (default 8000)
```

--------------------------------

### get_app

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Fetches the full record of a single app by its ID.

```APIDOC
## get_app

### Description
Fetches the full record of one app. Use `list_apps` to find IDs.

### Method
GET

### Endpoint
/apps/{appId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app to retrieve.
#### Query Parameters
- **verbosity** (string) - Optional - The level of detail to return. Allowed values: "standard", "full". Defaults to "standard".

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the app.
- **name** (string) - The name of the app.
- **href** (string) - The URL to access the app.
- **description** (string) - The description of the app.
- **iconUrl** (string) - The URL of the app's icon.
- **pingUrl** (string) - The URL to ping for the app's status.

### Request Example
```python
app = await server.get_app("app1", verbosity="full")
```

### Response Example
```json
{
  "id": "app1",
  "name": "Plex",
  "href": "https://plex.tv",
  "description": "Media server",
  "iconUrl": "https://cdn.example.com/plex.svg",
  "pingUrl": "https://plex.tv/health"
}
```
```

--------------------------------

### Run Tests

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/CONTRIBUTING.md

Executes tests using pytest, with verbose output.

```bash
uv run pytest tests/test_server.py -v
```

--------------------------------

### View Board Permissions

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Retrieves user and group permissions for a specified board.

```python
async def example():
    perms = await server.get_board_permissions("clx1")
    # {
    #   "userPermissions": [{"userId": "u1", "permission": "board-change"}],
    #   "groupPermissions": [{"groupId": "g1", "permission": "board-view"}]
    # }
```

--------------------------------

### Accessing Homarr MCP Settings (Python)

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Python code to access configuration settings loaded via Pydantic BaseSettings and mask credentials. Raises ValueError if HOMARR_API_KEY is not set.

```python
from src.config import settings, mask_credential

# Access config
print(settings.url)                         # "http://localhost:7575"
print(settings.has_api_key)                 # True / False
print(mask_credential(settings.get_api_key_value()))  # "ab**************en"

# get_api_key_value() raises ValueError if HOMARR_API_KEY is not set
key = settings.get_api_key_value()          # "abc123.secrettoken"
```

--------------------------------

### list_users

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Lists all users in the Homarr instance. The `standard` verbosity level includes `id`, `name`, `email`, `emailVerified`, and `image`.

```APIDOC
## list_users — List all users

Returns all users in the Homarr instance. `standard` verbosity includes `id`, `name`, `email`, `emailVerified`, `image`.

### Method Signature
`server.list_users(verbosity: str = "standard")`

### Parameters
- `verbosity` (str, optional): The level of detail to return. Defaults to "standard".

### Request Example
```python
users = await server.list_users(verbosity="standard")
# [
#   {"id": "u1", "name": "Alice", "email": "alice@example.com", "emailVerified": True, "image": None},
#   {"id": "u2", "name": "Bob",   "email": "bob@example.com",   "emailVerified": False, "image": None}
# ]
```
```

--------------------------------

### update_app

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Updates an existing app by fetching its current state and merging provided fields. Omitted fields are preserved.

```APIDOC
## update_app — Update an existing app

Fetches current app state first, then merges only the provided fields. Omitted fields are preserved from the current state.

### Method Signature
`server.update_app(app_id: str, **kwargs)`

### Parameters
- `app_id` (str): The ID of the app to update.
- `**kwargs`: Fields to update (e.g., `href`, `name`, `description`, `ping_url`).

### Request Example
```python
# Only update the URL — all other fields kept from current state
result = await server.update_app("app1", href="https://plex.example.com")
print(result)  # {"id": "app1", "name": "Plex", "href": "https://plex.example.com", ...}

# Update multiple fields at once
result = await server.update_app(
    "app1",
    name="Plex Media",
    description="Self-hosted Plex",
    ping_url="https://plex.example.com/health",
)
```
```

--------------------------------

### Search users by name or email

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Searches users using a query string. An optional 'limit' parameter can be provided, defaulting to 10.

```python
async def example():
    results = await server.search_users("alice", limit=5)
    # [{"id": "u1", "name": "Alice", "email": "alice@example.com", ...}]

    all_matches = await server.search_users("@example.com", limit=50)
```

--------------------------------

### Change Board Visibility

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Sets a board to be public or private. Accepts only 'public' or 'private' as valid visibility values.

```python
async def example():
    result = await server.change_board_visibility("clx1", "public")
    # {"id": "clx1", "isPublic": True}

    # Invalid value — no API call made
    err = await server.change_board_visibility("clx1", "hidden")
    print(err)  # {"error": "visibility must be 'public' or 'private'"}
```

--------------------------------

### Update an existing app

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Fetches current app state and merges provided fields, preserving omitted fields. Use to update specific app properties like URL or name.

```python
async def example():
    # Only update the URL — all other fields kept from current state
    result = await server.update_app("app1", href="https://plex.example.com")
    print(result)  # {"id": "app1", "name": "Plex", "href": "https://plex.example.com", ...}

    # Update multiple fields at once
    result = await server.update_app(
        "app1",
        name="Plex Media",
        description="Self-hosted Plex",
        ping_url="https://plex.example.com/health",
    )
```

--------------------------------

### get_board_permissions

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

View user and group permissions for a given board.

```APIDOC
## get_board_permissions

### Description
Returns a dict with `userPermissions` and `groupPermissions` arrays for the given board.

### Method
GET

### Endpoint
/boards/{boardId}/permissions

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The ID of the board to retrieve permissions for.

### Response
#### Success Response (200)
- **userPermissions** (array) - An array of user permission objects.
- **groupPermissions** (array) - An array of group permission objects.

### Response Example
```json
{
  "userPermissions": [{"userId": "u1", "permission": "board-change"}],
  "groupPermissions": [{"groupId": "g1", "permission": "board-view"}]
}
```
```

--------------------------------

### list_groups

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Lists all groups with their members. The `standard` verbosity level includes `id`, `name`, `ownerId`, `homeBoardId`, `mobileHomeBoardId`, and `members`.

```APIDOC
## list_groups — List all groups with members

Returns all groups. `standard` verbosity includes `id`, `name`, `ownerId`, `homeBoardId`, `mobileHomeBoardId`, `members`.

### Method Signature
`server.list_groups(verbosity: str = "standard")`

### Parameters
- `verbosity` (str, optional): The level of detail to return. Defaults to "standard".

### Request Example
```python
groups = await server.list_groups(verbosity="standard")
# [
#   {
#     "id": "g1", "name": "Admins", "ownerId": "u1",
#     "homeBoardId": "clx1", "mobileHomeBoardId": None,
#     "members": [{"id": "u1", "name": "Alice"}]
#   }
# ]
```
```

--------------------------------

### Duplicate Existing Board

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Copies an existing board to a new one with a specified name. Requires the source board's ID.

```python
async def example():
    # First get the board ID
    boards = await server.list_boards(verbosity="minimal")
    board_id = boards[0]["id"]  # "clx1"

    result = await server.duplicate_board(board_id, "Home (Copy)")
    print(result)  # {"boardId": "clxcopy"}
```

--------------------------------

### duplicate_board

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Copies all sections and items from an existing board into a new one.

```APIDOC
## duplicate_board

### Description
Copies all sections and items from an existing board into a new one identified by a new name. Requires the source board's ID.

### Method
POST

### Endpoint
/boards/{boardId}/duplicate

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The ID of the board to duplicate.
#### Request Body
- **newName** (string) - Required - The name for the new duplicated board.

### Request Example
```python
# First get the board ID
boards = await server.list_boards(verbosity="minimal")
board_id = boards[0]["id"]  # "clx1"

await server.duplicate_board(board_id, "Home (Copy)")
```

### Response
#### Success Response (201)
- **boardId** (string) - The ID of the newly created duplicated board.

### Response Example
```json
{"boardId": "clxcopy"}
```
```

--------------------------------

### Lint Code with Ruff

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Check code for linting errors using ruff check.

```bash
uv run ruff check src/ tests/
```

--------------------------------

### Delete an app

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Permanently removes an app tile by its ID. This action is irreversible.

```python
async def example():
    result = await server.delete_app("app1")
    print(result)  # {"success": True, "deleted_id": "app1", "result": None}
```

--------------------------------

### Add a user to a group

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Adds a specified user to an existing group. Both group ID and user ID are required.

```python
async def example():
    result = await server.add_group_member(group_id="g1", user_id="u2")
    print(result)  # {"success": True, "group_id": "g1", "user_id": "u2", "result": None}
```

--------------------------------

### delete_app

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Permanently deletes an app tile by its ID. This action is irreversible.

```APIDOC
## delete_app — Delete an app (irreversible)

Permanently removes an app tile by ID.

### Method Signature
`server.delete_app(app_id: str)`

### Parameters
- `app_id` (str): The ID of the app to delete.

### Request Example
```python
result = await server.delete_app("app1")
print(result)  # {"success": True, "deleted_id": "app1", "result": None}
```
```

--------------------------------

### Resolve Transport with CLI Override

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Demonstrates how the CLI argument `--streamable-http` overrides the environment variable `HOMARR_TRANSPORT` set to `sse`.

```python
_resolve_transport(argv=["--streamable-http"], env={"HOMARR_TRANSPORT": "sse"})  # "streamable-http"
```

--------------------------------

### Rename Board In-Place

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Renames an existing board using its ID and the new name.

```python
async def example():
    result = await server.rename_board("clx1", "Dashboard")
    print(result)  # {"id": "clx1", "name": "Dashboard"}
```

--------------------------------

### Claude Code MCP Configuration (JSON)

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

JSON configuration for integrating Homarr MCP with Claude Code, specifying the command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "homarr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/homarr-mcp", "python", "src/server.py"],
      "env": {
        "HOMARR_URL": "https://homarr.example.com",
        "HOMARR_API_KEY": "abc123.secrettoken"
      }
    }
  }
}
```

--------------------------------

### Commit Changes

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/CONTRIBUTING.md

Commits changes using the conventional commit format.

```bash
git commit -m 'feat: add some amazing feature'
```

--------------------------------

### Lint and Format Code

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/CONTRIBUTING.md

Checks for linting errors and ensures code formatting standards are met using ruff.

```bash
uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/
```

--------------------------------

### Configure Claude Code MCP Server

Source: https://github.com/tetra-2023/homarr-mcp/blob/master/README.md

Add this configuration to your Claude Code MCP settings to connect to the homarr-mcp server.

```json
{
  "mcpServers": {
    "homarr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/homarr-mcp", "python", "src/server.py"],
      "env": {
        "HOMARR_URL": "https://your-homarr-instance.com",
        "HOMARR_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### search_users

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Searches for users by name or email. An optional `limit` parameter can be provided to control the number of results, defaulting to 10.

```APIDOC
## search_users — Search users by name or email

Searches users with a query string and optional `limit` (default 10).

### Method Signature
`server.search_users(query: str, limit: int = 10)`

### Parameters
- `query` (str): The search string for user names or emails.
- `limit` (int, optional): The maximum number of results to return. Defaults to 10.

### Request Example
```python
results = await server.search_users("alice", limit=5)
# [{"id": "u1", "name": "Alice", "email": "alice@example.com", ...}]

all_matches = await server.search_users("@example.com", limit=50)
```
```

--------------------------------

### rename_board

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Renames a board in-place.

```APIDOC
## rename_board

### Description
Renames a board in-place. Requires board ID (from `list_boards`) and the new name.

### Method
PUT

### Endpoint
/boards/{boardId}

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The ID of the board to rename.
#### Request Body
- **newName** (string) - Required - The new name for the board.

### Request Example
```python
await server.rename_board("clx1", "Dashboard")
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the renamed board.
- **name** (string) - The new name of the board.

### Response Example
```json
{"id": "clx1", "name": "Dashboard"}
```
```

--------------------------------

### change_board_visibility

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Changes the visibility of a board to public or private.

```APIDOC
## change_board_visibility

### Description
Changes the visibility of a board. `visibility` must be exactly `"public"` or `"private"` — any other value returns `{"error": "..."}` without making an API call.

### Method
PUT

### Endpoint
/boards/{boardId}/visibility

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The ID of the board to update.
#### Request Body
- **visibility** (string) - Required - The desired visibility. Must be `"public"` or `"private"`.

### Request Example
```python
await server.change_board_visibility("clx1", "public")
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the board.
- **isPublic** (boolean) - The updated public status of the board.

#### Error Response (400)
- **error** (string) - Description of the error if the visibility value is invalid.

### Response Example
```json
{"id": "clx1", "isPublic": True}
```
```

--------------------------------

### get_group

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Retrieves a single group by its ID, including members and permissions. The `full` verbosity level provides the most comprehensive data.

```APIDOC
## get_group — Get a group by ID

Fetches a single group including members and permissions.

### Method Signature
`server.get_group(group_id: str, verbosity: str = "full")`

### Parameters
- `group_id` (str): The ID of the group to retrieve.
- `verbosity` (str, optional): The level of detail to return. Defaults to "full".

### Request Example
```python
group = await server.get_group("g1", verbosity="full")
# {
#   "id": "g1",
#   "name": "Admins",
#   "ownerId": "u1",
#   "members": [{"id": "u1", "name": "Alice", "email": "alice@example.com"}],
#   "permissions": [{"permission": "admin"}]
# }
```
```

--------------------------------

### Resolve Transport with Invalid Environment Fallback

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Shows that an invalid value for `HOMARR_TRANSPORT` in the environment falls back to the `stdio` transport when no CLI arguments are provided.

```python
_resolve_transport(argv=[], env={"HOMARR_TRANSPORT": "invalid"})        # "stdio"
```

--------------------------------

### Response Filtering

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Filters query tool responses based on verbosity level. 'full' bypasses filtering. Handles None inputs and unknown resource types.

```python
from src.server import _filter_response

boards = [
    {"id": "1", "name": "Home", "isPublic": True, "logoImageUrl": "/logo.png", "creator": "u1"}
]

minimal = _filter_response(boards, "board", "minimal")
# [{"id": "1", "name": "Home", "isPublic": True}]

standard = _filter_response(boards, "board", "standard")
# [{"id": "1", "name": "Home", "isPublic": True, "logoImageUrl": "/logo.png", "creator": "u1"}]

full = _filter_response(boards, "board", "full")
# [{"id": "1", "name": "Home", "isPublic": True, "logoImageUrl": "/logo.png", "creator": "u1"}]

# None passthrough
_filter_response(None, "board", "standard")  # None

# Unknown resource type — returns data unmodified
_filter_response({"custom": "data"}, "unknown", "standard")  # {"custom": "data"}
```

--------------------------------

### Delete Board Permanently

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Permanently deletes a board by its ID. Returns a success status and the deleted ID.

```python
async def example():
    result = await server.delete_board("clxold")
    print(result)  # {"success": True, "deleted_id": "clxold", "result": None}
```

--------------------------------

### delete_board

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Permanently deletes a board by ID.

```APIDOC
## delete_board

### Description
Permanently deletes a board by ID. Returns `{"success": True, "deleted_id": "<id>"}`.

### Method
DELETE

### Endpoint
/boards/{boardId}

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The ID of the board to delete.

### Request Example
```python
await server.delete_board("clxold")
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the deletion was successful.
- **deleted_id** (string) - The ID of the deleted board.
- **result** (null) - This field is always null.

### Response Example
```json
{"success": True, "deleted_id": "clxold", "result": null}
```
```

--------------------------------

### add_group_member

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Adds a user to an existing group. Both the group ID and user ID are required.

```APIDOC
## add_group_member — Add a user to a group

Adds a user to an existing group. Both IDs are required.

### Method Signature
`server.add_group_member(group_id: str, user_id: str)`

### Parameters
- `group_id` (str): The ID of the group.
- `user_id` (str): The ID of the user to add.

### Request Example
```python
result = await server.add_group_member(group_id="g1", user_id="u2")
print(result)  # {"success": True, "group_id": "g1", "user_id": "u2", "result": None}
```
```

--------------------------------

### Transport Resolution

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Resolves the server transport mechanism based on CLI flags or the HOMARR_TRANSPORT environment variable. CLI flags have higher priority.

```python
from src.server import _resolve_transport

# Default: stdio
_resolve_transport(argv=[], env={})                                     # "stdio"

# CLI flags (highest priority)
_resolve_transport(argv=["--sse"], env={})                              # "sse"
_resolve_transport(argv=["--streamable-http"], env={})                  # "streamable-http"

# Env var
_resolve_transport(argv=[], env={"HOMARR_TRANSPORT": "sse"})            # "sse"
```

--------------------------------

### Remove a user from a group

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Removes a member from a group without deleting the user or the group itself. Requires both group and user IDs.

```python
async def example():
    result = await server.remove_group_member(group_id="g1", user_id="u2")
    print(result)  # {"success": True, "group_id": "g1", "user_id": "u2", "result": None}
```

--------------------------------

### remove_group_member

Source: https://context7.com/tetra-2023/homarr-mcp/llms.txt

Removes a user from a group without deleting the user or the group itself.

```APIDOC
## remove_group_member — Remove a user from a group

Removes a member from a group without deleting the user or group.

### Method Signature
`server.remove_group_member(group_id: str, user_id: str)`

### Parameters
- `group_id` (str): The ID of the group.
- `user_id` (str): The ID of the user to remove.

### Request Example
```python
result = await server.remove_group_member(group_id="g1", user_id="u2")
print(result)  # {"success": True, "group_id": "g1", "user_id": "u2", "result": None}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.