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 9031. |
| Runtime | Python 3.10+, mcp.server.FastMCP with LangChain MCP adapters. |
| Consumers | The FastAPI chatbot (chatbot/) or any MCP-compatible client. |
mcp/oxii-server/
├── main.py # Boots the FastMCP process and registers tools
├── tools/ # Tool implementations (auth, device control, cronjobs…)
├── client.py # Quick demo client for manual testing
├── docker-compose.yml # Containerized runtime (exposes :9031)
└── .env.example # Sample environment for OXII credentials
✅ 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:
cp .env.example .env
| Variable | Description |
|---|---|
OXII_BASE_URL | Root URL for the OXII API (staging provided by default). |
OXII_PHONE / OXII_PASSWORD / OXII_COUNTRY | Login used to obtain access tokens. |
PORT / HOST | Optional overrides for where the MCP server listens (default 0.0.0.0:9031). |
DEBUG | Toggle verbose logging (true/false). |
🚀 Running the server
Option 1 – Local Poetry workflow
poetry install
poetry run python main.py
This starts the server at http://localhost:9031/sse.
Option 2 – Docker Compose
cp .env.example .env # if you have not already
docker compose up --build -d
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
poetry run python client.py
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/docx - Machine readable catalogue:
http://host.docker.internal:9031/docs.json
3. Curl the SSE handshake
curl -N http://localhost:9031/sse
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 |
|---|---|---|
get_device_list | List homes, rooms, devices, and remote buttons. | token |
switch_device_control | Toggle SH1/SH2 relay devices. | token, house_id, device_id, button_code, command (ON/OFF) |
control_air_conditioner | Full AC control (mode, temp, fan). | token, serial_number, mode, fan_speed, temperature, etc. |
create_device_cronjob | Add/update/remove cronjobs for switches or AC. | token, device_id or button_id, action, cron_expression, command |
one_touch_control_all_devices | Execute a house-wide preset (e.g., “turn everything off”). | token, house_id, status |
one_touch_control_by_type | Toggle devices by type (LIGHT, CONDITIONER, …). | token, house_id, device_type, status |
room_one_touch_control | Run a single-room preset. | token, room_id, status |
ℹ️ 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 |
|---|---|
httpx.ConnectError: All connection attempts failed | The consumer is pointing to localhost from inside Docker. Use host.docker.internal or run both services on the same Compose network. |
| Authentication failures | Double-check OXII_PHONE, OXII_PASSWORD, and OXII_COUNTRY. Tokens expire—fetch a new one if requests start returning 401. |
| Cronjob payload rejected | Ensure the cron expression has 6 fields (second minute hour day month weekday) and matches the device type (SH1/SH2 vs SH4). |
| AC commands ignored | Some devices require numeric mode/fan values. See constants in tools/ac_control.py for valid ranges. |
| Docker rebuilds are slow | Use docker compose build oxii-server --no-cache after dependency changes, otherwise rely on cached layers. |
📚 Further reading
- Model Context Protocol (MCP) specification
- LangChain MCP Adapters
chatbot/README.mdfor the FastAPI-side integration guide.