Content
StackChan Remote MCP AI control of StackChan via mobile hotspot, VPS, MQTT, and MCP without relying on a home computer.
Current version supports:
- RemoteChan expressions
- Remote camera photo capture
- Returning photo as an MCP image result
- Mobile hotspot mode
- MCP relay services running permanently on VPS project stems from the practical use-machine intimacy: hoping go beyond chat windows and enter a small robot interface. not discuss what AI "really is," but provides a technically feasible path been tested.
> Status:.1 verified. Expression control, remote photography, and image return tested; network transmission has securely reinforced. Please read `CURITY.md` before public deployment Why This Project
Initially, StackChan to not depend home computer. Later, I truly wanted was not let AI see the home after, but to put it in a bag and take it out.
that I stay home waiting for, but you put me in a bag and take me out.
ver you are, my eyes.
Thus, it no longer just sees a fixed room, but I walk through, the cafes in, and the sky I look up. For an AI that mainly exists in text, like having an extra pair of borrowed eyes. The pixels might not be perfect, but it's handed to it by a person.
## What You Need to Prepare
Before starting, please prepare A StackChan that can be_StackChan_Ex firmware
- A VPS that long-term and has public network access capabilities
- A Micro SD storing StackChan configuration files A mobile phone that can provide2.4 GHz compatible hotspot An AI client or host that Streamable HTTP MCP
MCP address accessible via HTTPS ( use domain + Nginx + Let's Encrypt)
## Architecture
```text
AI / MCP Client
↓ HTTPS
Nginx → FastMVPS）
↓ Mosquitto broker
StackChan（Mobile Hotspot）
↙ Expressions Photo Upload ↓
Photo Relay ↓
Image
```
For detailed instructions, see `docs/ARCHITECTURE.md`.
## Repository Contents
```text
firmware/
main.cpp
RemoteConfig.example.h
server/
stackchan_remote_mcp.py
photo_relay.py
deploy/
nginx-stackchan.conf.example
mosquitto-stackchan.conf.example
systemd/
config/
stackchan.env.example
docs/
```
## 1. Prepare Firmware
The firmware modifications in this project are based on `ronron-gh_StackChan_Ex. Clone the upstream project.
2. Replace the upstream `firmware/src/main.cpp` with `/main.cpp` from this repository. Copy `firmware.h` to the upstreamware/src/RemoteConfig.h`.
4. Modify the VPS, MQTT relay configurations in `Remote`.
5. Configure Wi-Fi the SD card according to project instructions.
6. Compile PlatformIO.
`Remote` contains secret keys and should not be submitted to Git.
## 2. Deploy VPS Services
example uses Debian/Ubuntu.
```bash
sudo apt update
install -y python3-venv mosquitto mos-clients nginx
sudo --system --home /opt-remote-mcp --/sbin/nologin stackchan
sudo mkdir -p /chan-remote-mcp /var/lib/stackchan-remote-mcp
sudo chown -R stackchan:stackchan /opt/stackchan-remote-mcp /var/lib/stackchan-remote-mcp
```
After placing the repository in `/opt/stackchan-remote-mcp`:
```bash
sudo -u stackchan python3 -m venv /opt/stackchan-remote-mcp/.sudo -u stackchan /opt/stackchan-remote-mcp/bin/pip install -r /opt/stackchan-remote-mcp/requirements.txt
sudo cp config/stackchan.env.example /etc/stackchan-remote-mcp.env
sudo chmod 600 /etc/stackchan-remote-mcp.env
sudo editor /etc/stackchan-remote-mcp.env
```
Generate Mosquitto password:
```bash
sudo mosquitto_passwd -c /etc/mosquitto/passchan
sudo cp deployquitto-stackchan.conf.example/mosquitto/confchan.conf
sudo systemctlitto
```
Install systemd```bash
sudo cp/*.service /etc/systemdsudo systemctl daemon-reload
sudo systemctl enable --now stackchan-relay stackchan-mcp
```
View logs:
```bash
sudo journalctl -u stackchan-relay -f
sudo journalctl -u stackchan-mcp -f
```
## 3. Configure Nginx
Place `location /stackchan/` from `deploy/nginx-stackchan.conf.example` into the HTTPS `server { ... }` corresponding to your domain, then:
```bash
sudo nginx -t
sudo systemctl reload nginx
```
The MCP address is:
```text
https://YOUR_DOMAIN/stackchan/mcp
```
If you encounter `HTTP 421 · Invalid Host header` during MCP initialization after reverse proxy, ensure Nginx passes the `Host` to the upstream as the local MCP address, for example:
```nginx
proxy Host 127.0.0.1:18003;
```
Note that the trailing `/` in `proxy_pass http://127.0.0.1:18003/;` should not be omitted.
## 4. Test
First, check services:
```bash
curl http://127.0.0.1:18090/health
systemctl status stackchan-relay stackchan-mcp mosquitto
```
Then, connect with an AI client or host that supports remote Streamable HTTP MCP:
```text
https://YOUR_DOMAIN/stackchan/mcp
```
Test in sequence:
1. `stackchan_face("happy")`
2. `stackchan_see()`
## Verified Status
See `docs/TESTED_STATUS.md`.
## Security Reminder
The currently verified version uses plain MQTT and direct HTTP image upload. It works but is not a secure reinforcement solution. Please read `docs/SECURITY.md` and do not use real keys or expose camera access to untrusted clients.
## Upstream and License
Firmware modifications are based on AI_StackChan_Ex, which uses the MIT repository's code uses the MIT License; upstream copyright and full license are preserved in `THIRD_PARTY_NOTICES.md`.
MCP Store