Provides comprehensive smart home device control through OXII platform, including device switching, air conditioner management, cronjob scheduling, and room-based automation scenarios
OXII Smart Home MCP Server
Modern documentation for the device-control MCP stack that pairs with the FastAPI chatbot. Use this guide the same way you would the chatbot docs: it covers setup, commands, tooling, and troubleshooting for standalone MCP development.
🔎 Overview
Purpose | Expose OXII smart home controls (device info, switching, AC, cronjobs, one-touch, room scenarios) via the Model Context Protocol (MCP). |
Transport | Server Sent Events (SSE) on port
. |
Runtime | Python 3.10+, with LangChain MCP adapters. |
Consumers | The FastAPI chatbot (
) or any MCP-compatible client. |
✅ Prerequisites
Python 3.10 or newer (Poetry will manage dependencies), or Docker Engine 20.10+
OXII account credentials with device access (phone, password, country)
Network access to the OXII staging/prod API defined in
OXII_BASE_URL
⚙️ Environment configuration
Create a working copy of the environment file and fill in the secrets:
Variable | Description |
| Root URL for the OXII API (staging provided by default). |
/
/
| Login used to obtain access tokens. |
/
| Optional overrides for where the MCP server listens (default
). |
| Toggle verbose logging (
/
). |
🚀 Running the server
Option 1 – Local Poetry workflow
This starts the server at http://localhost:9031/sse.
Option 2 – Docker Compose
The compose stack exposes port 9031 on the host. Combine this with the chatbot by pointing OXII_MCP_SERVER_URL to http://host.docker.internal:9031/sse inside the chatbot container.
✅ Verifying the service
1. Use the bundled client
Select a tool from the prompt and provide the required parameters to confirm end-to-end connectivity.
2. Visit the built-in docs UI
Human friendly docs:
http://host.docker.internal:9031/docxMachine readable catalogue:
http://host.docker.internal:9031/docs.json
3. Curl the SSE handshake
You should see an initial JSON payload describing the MCP capabilities.
🧰 Tool catalogue
Below is a quick reference for each registered MCP tool. All payloads are JSON structures passed through the MCP protocol.
Tool | Purpose | Key parameters |
| List homes, rooms, devices, and remote buttons. |
|
| Toggle SH1/SH2 relay devices. |
,
,
,
,
(
/
) |
| Full AC control (mode, temp, fan). |
,
,
,
,
, etc. |
| Add/update/remove cronjobs for switches or AC. |
,
or
,
,
,
|
| Execute a house-wide preset (e.g., “turn everything off”). |
,
,
|
| Toggle devices by type (LIGHT, CONDITIONER, …). |
,
,
,
|
| Run a single-room preset. |
,
,
|
ℹ️ Detailed schemas live in
tools/next to each function. Review those modules for argument validation and API payload shapes.
🔄 Working with the chatbot
Start the MCP server (local or Docker) and ensure port
9031is reachable from the chatbot environment.In
chatbot/.env, setOXII_MCP_SERVER_URL=http://host.docker.internal:9031/ssewhen running the chatbot in Docker.Restart the chatbot container (
docker compose restart app) to apply env changes.Use the chatbot endpoint
POST /ai/agent-oxiiwith a valid OXII token—the agent will automatically call the MCP tools.
🧪 Testing & diagnostics
Unit checks – Run
poetry run pytestif you add tests (seed filetest_tools.pyis available as a template).Token validation – Use
chatbot/test_folders/testing_api.pyto fetch a fresh token before invoking tools.Logs – With
DEBUG=true, the server prints detailed traces for each MCP call. In Docker, view them withdocker compose logs -f oxii-server.
🛠 Troubleshooting
Symptom | Suggested fix |
| The consumer is pointing to
from inside Docker. Use
or run both services on the same Compose network. |
Authentication failures | Double-check
,
, and
. Tokens expire—fetch a new one if requests start returning 401. |
Cronjob payload rejected | Ensure the cron expression has 6 fields (
) and matches the device type (SH1/SH2 vs SH4). |
AC commands ignored | Some devices require numeric mode/fan values. See constants in
for valid ranges. |
Docker rebuilds are slow | Use
after dependency changes, otherwise rely on cached layers. |
📚 Further reading
chatbot/README.mdfor the FastAPI-side integration guide.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables control of OXII smart home devices through the Model Context Protocol, supporting device switching, air conditioner control, cronjobs, and room scenarios. Integrates with chatbots and MCP-compatible clients for natural language home automation.