Overview

The OctoEverywhere MCP (Model Context Protocol) server provides a lightweight HTTP + WebSocket bridge that lets developer applications query and control a 3D printer in real time. It exposes a small set of endpoints for reading live printer state, capturing webcam snapshots, and sending remote commands — all designed to be easy to integrate into custom dashboards, automation scripts, or third‑party services.

This server is useful when you need a simple, programmatic interface to a printer behind a local network or when you want to consolidate state and camera access in a single service layer. It is lightweight and can be run on the same machine as your printer stack (Raspberry Pi / OctoPrint host) or in a container, and it is intended for developers who want direct programmatic control without implementing their own full stack integration.

Features

Query live printer state (status, temperatures, job progress)
Capture webcam snapshots on demand
Send remote commands (start/stop/pause, G-code, plugin actions)
WebSocket channel for real‑time notifications and bi‑directional control
Simple token‑based authentication and configurable CORS
Lightweight Node.js server suitable for containerized deployment

Installation / Configuration

Prerequisites: Node.js (14+) or Docker.

Clone and install:

git clone https://github.com/OctoEverywhere/mcp.git
cd mcp
npm install

Configure environment variables (example .env):

PORT=3000
API_TOKEN=replace_with_a_secure_token
PRINTER_BASE_URL=http://localhost:5000  # base URL to your printer API (OctoPrint or similar)
WEBCAM_SNAPSHOT_URL=http://localhost:8080/?action=snapshot
CORS_ORIGINS=http://localhost:8081  # comma-separated allowed origins

Start the server:

# dev
npm start

# or run directly with node
node server.js

Docker (optional):

docker run -d \
  -p 3000:3000 \
  -e API_TOKEN=replace_with_a_secure_token \
  -e PRINTER_BASE_URL=http://host.docker.internal:5000 \
  -e WEBCAM_SNAPSHOT_URL=http://host.docker.internal:8080/?action=snapshot \
  octoeverywhere/mcp:latest

Security notes: use a strong API token, run behind TLS or a reverse proxy when exposing to untrusted networks, and restrict CORS to known origins.

Available Resources

The server exposes a small REST surface plus a WebSocket channel. Exact path prefixes may vary by release; examples below show common routes.

Endpoints

Method	Path	Description
GET	/mcp/state	Current printer state (status, temps, job progress)
GET	/mcp/snapshot.jpg	One-off webcam snapshot (JPEG)
POST	/mcp/command	Send a remote command (JSON)
GET	/mcp/ws	WebSocket upgrade endpoint for real‑time events

Authentication: include an Authorization header:

Authorization: Bearer <API_TOKEN>

Example REST calls

Get printer state:

curl -H "Authorization: Bearer $API_TOKEN" \
  https://your-mcp.example.com/mcp/state

Fetch a webcam snapshot:

curl -H "Authorization: Bearer $API_TOKEN" \
  https://your-mcp.example.com/mcp/snapshot.jpg --output snapshot.jpg

Send a command (e.g., pause):

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '{"command":"pause"}' \
  https://your-mcp.example.com/mcp/command

WebSocket usage (browser/Node.js example)

const token = "your_token_here";
const ws = new WebSocket("wss://your-mcp.example.com/mcp/ws", {
  headers: { Authorization: `Bearer ${token}` }
});

ws.onopen = () => console.log("connected");
ws.onmessage = (evt) => {
  const message = JSON.parse(evt.data);
  console.log("event", message);
};
// send a command over WebSocket
ws.send(JSON.stringify({ type: "command", command: "resume" }));

Events typically include state updates (temperatures, progress) and command responses.

Use Cases

Custom monitoring dashboard: Poll /mcp/state every few seconds and display live temperatures, bed/nozzle status, and print progress in a web UI. Use /mcp/snapshot.jpg to show a current camera image.
Remote control integration: Use POST /mcp/command to implement “pause”, “resume”, “cancel” buttons in a mobile app or home automation rule — include command payloads as JSON.
Real‑time notifications and automation: Subscribe to the WebSocket for immediate events (print finished, errors) and trigger downstream automation (send notification, start cooling, upload logs).
Automated timelapse or snapshot capture: Call /mcp/snapshot.jpg on a schedule to build a timelapse or feed images to an analysis tool (print quality detection).
Testing and CI: Use the command API to programmatically run short test prints or execute G-code snippets as part of an automated validation pipeline.

Additional Resources

Repository and source code: https://github.com/OctoEverywhere/mcp
Typical environment variables: PORT, API_TOKEN, PRINTER_BASE_URL, WEBCAM_SNAPSHOT_URL, CORS_ORIGINS
Recommended deployment: run behind HTTPS reverse proxy (nginx, Caddy) and restrict access with firewall rules or VPN

This MCP server is intended to be a simple, developer‑friendly bridge to your printer and webcam. For any advanced customization, consult the repository README and source to adapt endpoints and authentication to your environment.

OctoEverywhere MCP Server for Live 3D Printer Control