Skip to content

# Package Management Tool

The Package Management tool provides functionality to manage Home Assistant Community Store (HACS) packages through the MCP interface.

## Features

- List available packages
- Install/update/remove packages
- Search packages
- Get package information
- Manage package repositories
- Track package updates
- View package documentation
- Monitor package status

## Usage

### REST API

    GET /api/packages
    GET /api/packages/{package_id}
    POST /api/packages/{package_id}/install
    POST /api/packages/{package_id}/uninstall
    POST /api/packages/{package_id}/update
    GET /api/packages/search
    GET /api/packages/categories
    GET /api/packages/repositories

### WebSocket

    // List packages
    {
        "type": "get_packages",
        "category": "optional_category"
    }

    // Search packages
    {
        "type": "search_packages",
        "query": "search_query",
        "category": "optional_category"
    }

    // Install package
    {
        "type": "install_package",
        "package_id": "required_package_id",
        "version": "optional_version"
    }

## Package Categories

- Integrations
- Frontend
- Themes
- AppDaemon Apps
- NetDaemon Apps
- Python Scripts
- Plugins

## Examples

### List All Packages

    const response = await fetch('http://your-ha-mcp/api/packages', {
        headers: {
            'Authorization': 'Bearer your_access_token'
        }
    });
    const packages = await response.json();

### Search Packages

    const response = await fetch('http://your-ha-mcp/api/packages/search?q=weather&category=integrations', {
        headers: {
            'Authorization': 'Bearer your_access_token'
        }
    });
    const searchResults = await response.json();

### Install Package

    const response = await fetch('http://your-ha-mcp/api/packages/custom-weather-card/install', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "version": "latest"
        })
    });

## Response Format

### Package List Response

    {
        "success": true,
        "data": {
            "packages": [
                {
                    "id": "package_id",
                    "name": "Package Name",
                    "category": "integrations",
                    "description": "Package description",
                    "version": "1.0.0",
                    "installed": true,
                    "update_available": false,
                    "stars": 150,
                    "downloads": 10000
                }
            ]
        }
    }

### Package Info Response

    {
        "success": true,
        "data": {
            "package": {
                "id": "package_id",
                "name": "Package Name",
                "category": "integrations",
                "description": "Package description",
                "long_description": "Detailed description",
                "version": "1.0.0",
                "installed_version": "0.9.0",
                "available_version": "1.0.0",
                "installed": true,
                "update_available": true,
                "stars": 150,
                "downloads": 10000,
                "repository": "https://github.com/author/repo",
                "author": {
                    "name": "Author Name",
                    "url": "https://github.com/author"
                },
                "documentation": "https://github.com/author/repo/wiki",
                "dependencies": [
                    "dependency1",
                    "dependency2"
                ]
            }
        }
    }

### Search Response

    {
        "success": true,
        "data": {
            "results": [
                {
                    "id": "package_id",
                    "name": "Package Name",
                    "category": "integrations",
                    "description": "Package description",
                    "version": "1.0.0",
                    "score": 0.95
                }
            ],
            "total": 42
        }
    }

## Error Handling

### Common Error Codes

- `404`: Package not found
- `401`: Unauthorized
- `400`: Invalid request
- `409`: Package operation failed
- `422`: Invalid configuration
- `424`: Dependency error

### Error Response Format

    {
        "success": false,
        "message": "Error description",
        "error_code": "ERROR_CODE"
    }

## Rate Limiting

- Default limit: 50 requests per 15 minutes
- Configurable through environment variables:
- `PACKAGE_RATE_LIMIT`
- `PACKAGE_RATE_WINDOW`

## Best Practices

1. Check package compatibility
2. Review package documentation
3. Verify package dependencies
4. Back up before updates
5. Test in safe environment
6. Monitor resource usage
7. Keep packages updated
8. Handle rate limiting gracefully

## Package Security

- Verify package sources
- Review package permissions
- Check package reputation
- Monitor package activity
- Keep dependencies updated
- Follow security advisories

## See Also

- Add-on Management
- Device Control
- Event Subscription

February 5, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings