ipcam-mcp

An MCP server that lets Claude Code see through and control the IP cameras on your local network (ONVIF + RTSP): snapshots, video clips, pan/tilt and change detection, all handled locally.

Any ONVIF camera should work. See known cameras for what has been tested.

Tools

camera is a camera's name: its section name in cameras.toml. quality="high" uses the camera's main stream (1080p), "low" the sub stream (smaller, quicker). Media is saved to the camera's own folder, <media_dir>/<uid>/<camera>_<YYYYmmdd-HHMMSS>.jpg|.mp4 (media_dir defaults to ~/.local/share/ipcam-mcp/media).

Tool hints. Every tool carries MCP annotations so clients can tell what it does: list_cameras, list_scenes, scene_timeline and ptz_list_presets are read-only; camera_save_baseline, ptz_save_preset, ptz_remove_preset, remove_camera and delete_camera may replace or delete data; everything else only adds files or moves the camera. Snapshots and recordings are not marked read-only because they save files. These are hints for the client; the server's own safeguards (such as delete_camera's approval form) still apply.

Compare and crop. camera_compare lists the grid cells that changed (the same names as region) and a box around them. Pass a changed cell as region to camera_snapshot, ideally with from_path set to the snapshot you just looked at, to see it closer. Baselines live in <media_dir>/<uid>/baselines/ as a JPEG plus a small JSON file.

Camera uids. Every camera has a permanent uid (8 characters, a-z0-9) in its cameras.toml section. The server fills it in when it is missing, so you never write one yourself; don't change or copy it. The uid names the camera's media folder, which also holds a camera.json with the camera's current name. Because of it, a renamed camera keeps its snapshots and baselines, and a new camera that reuses an old name starts with an empty history. When you upgrade from 0.2, the first start moves existing snapshots, recordings and baselines from the old flat layout into these folders; files of cameras that are no longer configured get a folder of their own and are kept.

Scenes. A scene is the place a camera watches, such as front-door or garage. By default it is the camera's name; set scene = "..." in the camera's section (or use set_scene) when they differ, for example when several cameras watch one place. Renaming a camera keeps its scene. Moving a camera to another scene starts a new period in its camera.json: snapshots and baselines from before the move stay with the old scene, and camera_compare only compares within the current one, so it never reports a different place as a change.

Replacing a camera. When a camera enters a scene where a removed camera was last (with add_camera, or set_scene), you are asked in a form whether it replaces one of them, is an additional camera, or to cancel. A replacement is its successor: until it has a snapshot of its own there, camera_compare compares with the old camera's newest snapshot in the scene, and baselines are looked up along the predecessors (up to 10). The result then says which camera took the reference, since angle, lens or resolution may differ. Without form support the camera is added as an additional one; call set_scene with its current scene later, from a client that shows forms, to declare it a successor. A camera that moves away and later returns to the scene keeps its predecessor there. delete_camera mentions when a camera is another's predecessor.

Prerequisites

• Linux or WSL2, on the same network as the camera
• uv on your PATH (it installs Python 3.13+ and the dependencies for you)
• ffmpeg: sudo apt install ffmpeg
• An ONVIF-capable IP camera with a local camera account (username and password), with ONVIF and RTSP enabled
• Claude Code or another MCP client that supports stdio servers

Setup

1. Install: nothing to do if you run it with uvx ipcam-mcp (see step 5); uv fetches it from PyPI. To work on the code, or to use the project-scoped .mcp.json, clone it instead:

   git clone https://github.com/aidev-iprokszin/ipcam-mcp.git && cd ipcam-mcp && uv sync
   

2. Camera account: create or find the camera's local ONVIF/RTSP account (username and password). This is not your cloud login. See known cameras for where your brand hides it.

3. Secrets file (outside the repo), e.g. ~/.config/ipcam-mcp/secrets.env:

   CAMERA_IP=192.168.x.y
   CAMERA_USER=...
   CAMERA_PASSWORD=...
   

   Make it readable only by you: chmod 600 <file>. The server warns at startup if other users can read it.

4. Camera config: copy cameras.example.toml to ~/.config/ipcam-mcp/cameras.toml (or point IPCAM_MCP_CONFIG at another path) and adjust the camera name / variable names. Only variable names go in this file, never the secrets themselves. Use type = "onvif".

   Steps 3 and 4 are optional if you let Claude add cameras: without a config file the server starts with no cameras, and add_camera (see Managing cameras) creates cameras.toml and the camera's secrets file for your first camera.

5. Use it in Claude Code: install the plugin, which runs the PyPI package with uvx:

   /plugin install ipcam --marketplace aidev-iprokszin/ipcam-mcp
   

   On Claude Code older than 2.1.275, run /plugin marketplace add aidev-iprokszin/ipcam-mcp, then /plugin install ipcam@ipcam-mcp. Update it with claude plugin update ipcam@ipcam-mcp; the plugin pins the server version, so this also updates the server.

   Without the plugin, register the PyPI package in your user scope:

   claude mcp add ipcam -s user -- uvx ipcam-mcp
   

   In a clone, the repo ships a project-scoped .mcp.json, so running claude anywhere inside this repo offers the ipcam server. Approve it when prompted. If you rejected it by mistake, run claude mcp reset-project-choices and start claude again. Then ask Claude e.g. "list my cameras" or "take a snapshot of livingroom".

   To use it from every folder, also register it in your user scope (inside the repo the project entry takes precedence, so there are no duplicates):

   claude mcp add ipcam -s user -- uv --directory /absolute/path/to/ipcam-mcp run ipcam-mcp
   

Camera settings

All optional, set in the camera's section of cameras.toml. A wrong type is reported when the config loads.

ptz = false means the camera has no pan/tilt tools. Set stream_high/stream_low if the ONVIF lookup fails or picks the wrong stream. Set invert_pan = true if ptz_move left turns the view to the right. Some brands need other values; see known cameras.

Other MCP clients

Any client that supports stdio servers (Cursor, VS Code, Codex CLI, …) can run the same command: uvx ipcam-mcp, or uv --directory /absolute/path/to/ipcam-mcp run ipcam-mcp for a clone.

Claude Desktop on Windows with the repo in WSL (untested): add to %APPDATA%\Claude\claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "ipcam": {
      "command": "wsl.exe",
      "args": ["-e", "/home/<you>/.local/bin/uv", "--directory",
               "/home/<you>/path/to/ipcam-mcp", "run", "ipcam-mcp"]
    }
  }
}

WSL2 networking

If the camera can't be reached from WSL (nc -zv <ip> 554 fails), enable mirrored networking in %UserProfile%\.wslconfig:

[wsl2]
networkingMode=mirrored

then run wsl --shutdown from Windows.

Managing cameras

Instead of editing cameras.toml by hand you can let Claude add, rename, remove and delete cameras. This is on by default. To turn it off, set allow_management = false in cameras.toml (see cameras.example.toml), then run /mcp reconnect ipcam; the flag is only read at startup. Claude Code still asks before each tool call unless you allowlist it; if you allowlist the camera tools, consider leaving remove_camera, delete_camera and ptz_remove_preset off the list.

add_camera logs into whatever host it is given. Before you type a password into the login form, check that the IP it shows is your camera's (from the camera's app or your router), not one the agent picked up elsewhere.

Changes apply immediately, without restarting the server. If loading the new config fails, the previous cameras.toml is restored.

IP address. Network discovery is not supported (WSL2 NAT blocks it), so tell Claude the camera's IP from the camera's app or your router.

Credentials never pass through the model. Two routes:

• Form (default): your client shows a login form. MCP forms have no masked field, so the password is visible while you type it, but it is not stored in the conversation. Clients on MCP protocol 2026-07-28 cannot show the form mid-call, and neither can some phone (Remote Control) views; there add_camera always uses the secrets-file route and says so in its result.
• File (credentials_via="file"): add_camera creates <secrets_dir>/<name>.env (mode 0600, default secrets_dir is ~/.config/ipcam-mcp/secrets) with HOST=, empty USER= and PASSWORD=. Fill in USER and PASSWORD yourself, then ask Claude to call add_camera again with the same name and host, keeping credentials_via="file". Calling it with the default form would ask for the credentials again instead of reading the file.

Each camera added this way has its own <name>.env, and files at <secrets_dir>/<name>.env are treated as managed: renamed and deleted along with the camera. Keep hand-made files elsewhere; those, such as a shared secrets.env, are never renamed or deleted. Secrets files are read literally: ${VAR} in a value is not expanded.

Transports

ipcam-mcp uses stdio by default. ipcam-mcp --transport http [--host 127.0.0.1] [--port 8765] serves streamable HTTP, but without authentication, so only use it on a trusted machine and keep it bound to localhost. On 127.0.0.1, localhost or ::1 the server rejects requests addressed to other hosts, such as from web pages (DNS-rebinding protection). Any other --host is refused unless you also pass --allow-remote; then anyone who can reach the port controls your cameras.

Security

See SECURITY.md for the threat model and how to report a vulnerability.

• Credentials are read only from your secrets file, never from the repo, and are not put into environment variables.
• They are kept in memory by the camera's config and adapter, and are excluded from repr.
• The password is scrubbed (raw and URL-encoded) from every error message the server returns or logs.
• RTSP URLs are masked (rtsp://***@host…), which also hides the username. The username is not scrubbed anywhere else.
• Logs go to stderr; stdout carries only the MCP protocol.

Troubleshooting

• Auth errors / 401 / ONVIF error on every PTZ call: use the camera's local account, not a cloud login. See known cameras.
• Snapshots fail but ONVIF works: set stream_high/stream_low (see Camera settings).
• timed out … (camera unreachable?): the camera is offline or not reachable from this machine. See WSL2 networking.
• ffmpeg not installed: sudo apt install ffmpeg.
• camera.json … unreadable, kept as camera.json.bad-… in the log: a camera's camera.json could not be read (for example after a bad hand edit), so a new one was written and the old one kept next to it. To get the camera's creation time and scene history back, fix the kept file and rename it to camera.json while the server is stopped (scene changes made since are then lost; redo them with set_scene). Timestamps without a UTC offset are read as local time.

Known limitations

• While the camera is offline, failed ONVIF connection attempts aren't cleaned up, and you may see Unclosed client session warnings on stderr. They're harmless.
• Filenames have one-second resolution; a second capture in the same second gets a -2, -3, … suffix.
• Filenames carry local time without a UTC offset. In the hour that repeats when daylight saving time ends, a capture counts as taken in the first of the two hours, and after the machine's time zone changes, older captures shift by the difference. Both only matter for captures close to a scene change: they can be assigned to the neighbouring scene.
• Media files are never deleted. Clean up ~/.local/share/ipcam-mcp/media/ yourself.
• HTTP transport has no authentication (see above).

Upgrading from 0.2

• On the first start, every camera in cameras.toml gets a permanent uid = "..." line, and existing snapshots, recordings and baselines move from the flat layout into per-camera folders, <media_dir>/<uid>/. Files of cameras that are no longer configured are kept in folders of their own (removed cameras: list_cameras(include_removed=true), delete_camera). Only files named like a camera's capture (<name>_YYYYmmdd-HHMMSS.jpg|mp4, where <name> is a configured camera or a valid camera name: a-z, 0-9, -, _) move; other files, such as IMG_… photos, stay. A file whose target already exists is left in place with a warning. Once the move has finished, an empty .flat-layout-migrated file in media_dir keeps it from running again; delete it to repeat the migration. cameras.toml must be writable while cameras still need a uid: a read-only file is not changed, and the server stops with an error. (The server never replaces a read-only cameras.toml; management tools then fail with "it is read-only".)
• Every camera is in a scene, by default its name, so existing snapshots and baselines stay in scenes named after their cameras. camera_compare now compares only within the camera's current scene.
• add_camera and remove_camera take name instead of id.
• New tools: delete_camera, set_scene, list_scenes, scene_snapshot, scene_compare, scene_timeline. camera_snapshot accepts from_path without camera.

Development

uv run pytest            # unit tests (no network; the preview test is skipped without ffmpeg)
uv run pytest -m live    # against the real camera from your config (IPCAM_MCP_CAMERA, default livingroom)
IPCAM_MCP_CAMERA=office uv run pytest -m live    # e.g. against another configured camera
uv run ruff check . && uv run ruff format .

⚠️ The live tests physically move the camera (a small pan left and back) and save snapshots and a 3 s clip to the media folder. They also create and delete a preset and a baseline, both named cmcp_test.

Adding a camera type

1. Add an adapter in src/ipcam_mcp/adapters/ taking (DeviceConfig, media_dir) and implementing the Camera protocol (and PTZ if it can pan/tilt) from src/ipcam_mcp/capabilities.py.
2. Map its config type to the adapter in ADAPTERS in src/ipcam_mcp/registry.py.

A new camera feature (e.g. privacy mode) gets a Protocol in capabilities.py, registered in CAPABILITIES, plus its tools in src/ipcam_mcp/server.py.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md and the Code of Conduct.

This project was built with Claude Code.

License

MIT