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).

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.

Related MCP server: OBSBOT Camera MCP Server

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. Clone and install:

   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: 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: uv --directory /absolute/path/to/ipcam-mcp run ipcam-mcp.

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 and remove 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 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.

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.

• Media files are never deleted. Clean up ~/.local/share/ipcam-mcp/media/ yourself.

• HTTP transport has no authentication (see above).

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