xenarathon/boxxo-tools-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
76 commits 1 branch 0 tags 2.2 MiB
Find a file
Exact
xenarathon 5cdc390903 feat(changelog): add add_changelog_entry / get_recent_changelog tools 
Wired to the new Changelog table on the F.A.S.C. Saltcorn site's REST API
(Bearer token auth). Household-only (not in PUBLIC_TOOLS) — the public bot
doesn't get to write to the site.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-17 17:44:17 -04:00
docs docs(plan): Phase 3b.5 + 3b specs and implementation plan 2026-07-11 22:07:00 -04:00
tests feat(tools): add lookup_infrastructure — hardware/IP directory for Boxxo 2026-07-14 17:43:45 -04:00
.env.example feat(changelog): add add_changelog_entry / get_recent_changelog tools 2026-07-17 17:44:17 -04:00
.gitignore feat(calendar): family calendar tools over Nextcloud CalDAV 2026-07-07 14:15:46 -04:00
compose.yaml compose(boxxo-tools): add /data volume for the per-user profile store 2026-07-10 14:49:34 -04:00
conftest.py feat(calendar): family calendar tools over Nextcloud CalDAV 2026-07-07 14:15:46 -04:00
Dockerfile Add web_search tool (provider-switchable: ddgs/Tavily/Brave/SearXNG); switch to native MCP streamable-http (drop mcpo) 2026-07-07 13:06:39 -04:00
LICENSE feat(discord): announce_family tool for the family Discord channel 2026-07-07 15:27:39 -04:00
README.md Boxxo Tools MCP server: 17 tools ported 1:1 from Open WebUI tools (utility/media/health/HA), mcpo→OpenAPI packaging 2026-07-07 10:43:11 -04:00
requirements-dev.txt feat(calendar): family calendar tools over Nextcloud CalDAV 2026-07-07 14:15:46 -04:00
requirements.txt feat(calendar): family calendar tools over Nextcloud CalDAV 2026-07-07 14:15:46 -04:00
server.py feat(changelog): add add_changelog_entry / get_recent_changelog tools 2026-07-17 17:44:17 -04:00

README.md

Boxxo Tools MCP

A single MCP server exposing the homelab tools that Boxxo (the F.A.S.C. household assistant) uses — weather/time, media status, service health, and Home Assistant read + scoped control. Because it speaks MCP, the same tools work across any MCP/OpenAPI client: Open WebUI (via the mcpo proxy), Home Assistant Assist, Claude Desktop, LibreChat, and more — instead of being re-implemented per frontend.

Built with Claude (Opus 4.8). The tool logic is ported 1:1 from the original Open WebUI Python tools so behaviour is identical.

What's inside (17 tools)

Group Tools
Utility get_current_datetime, get_weather, get_forecast
Media status (read-only) get_active_downloads, get_arr_queue, get_recently_added
Service health (read-only) check_service, check_all_services
Home Assistant reads: get_entity_state, list_entities · scoped control: set_light, set_switch, activate_scene, run_script, set_climate_temperature, set_media_volume, control_media

Reads are safe. HA control is domain-scoped and requires an explicit, resolved target — ambiguous or unknown names are refused (never guesses), and each action is confirmed by re-reading the entity.

Run it

Quick start (Docker) 
# 1. build the image (DockHand can't build — build on a host and reference the tag)
docker build -t boxxo-tools-mcp:latest .

# 2. configure secrets
cp .env.example boxxo.env    # then edit boxxo.env with your qBit/Sonarr/Radarr/HA creds

# 3. run — mcpo wraps the MCP server and serves OpenAPI on :8100
docker compose up -d

# 4. check
curl -s http://localhost:8100/openapi.json | python3 -c "import sys,json;print(len(json.load(sys.stdin)['paths']),'tools')"
Wire it into Open WebUI

Admin → Settings → Tools → add an OpenAPI tool server:

  • URL: http://<host>:8100
  • Auth: Bearer, key = your MCPO_API_KEY

Then attach the tools to your model (e.g. Boxxo).

Personalize (change these for your setup)
  • boxxo.env — all endpoints + credentials (qBit/Sonarr/Radarr/HA) and weather defaults.
  • server.py → SERVICES — the fleet map for service_health (name → URL). Edit to match your services.
  • Weather — WEATHER_LOCATION / WEATHER_TZ / WEATHER_UNITS in boxxo.env.

Notes

  • Runs the MCP server over stdio; mcpo exposes each tool as an OpenAPI endpoint.
  • HA control tools default to safe read-then-act with a settle-poll (slow BRMesh/Govee/Alexa devices confirm state slowly).

License

GPL-3.0-or-later.