Back to search
camctl
MCP serverGitHub
CLI + MCP server for cameras over USB PTP, Wi-Fi PTP/IP and Bluetooth LE, with md5-verified Google Drive card offload. Verified on a Sony A7 V.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/jackulau--camctl)HTML
<a href="/listings/jackulau--camctl"><img src="/api/listings/jackulau--camctl/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/jackulau/camctl.git && cd camctl uv sync uv run camctl doctor --fix # checks USB/BLE/Drive; frees the camera from macOS ptpcamerad
Use as an MCP server (Claude Code shown; any MCP client works):
claude mcp add camctl -- uv --directory /path/to/camctl run camctl-mcp
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 284 lines
- # camctl
- Control your camera from the command line or from an AI assistant, with no vendor app. camctl is a CLI and an
- [MCP](https://modelcontextprotocol.io) server that changes settings, applies presets, shoots, records, runs live
- view, acts as a Bluetooth remote, and offloads cards to Google Drive with md5 verification.
- It was built and verified on a **Sony A7 V (ILCE-7M5)**. Canon, Nikon, Fujifilm, Panasonic and OM System are
- supported through libgphoto2 and published Bluetooth protocols, but are **untested on hardware**. Reports and fixes
- from owners are welcome.
- | Transport | What works |
- |---|---|
- | **USB-C (PTP)** | Every setting the camera exposes: presets, dump/load/diff config, capture, record, live view |
- | **Wi-Fi (PTP/IP)** | Same as USB via `--port ptpip:<camera IP>` (Sony: PC Remote Cnct Method: Wi-Fi) |
- | **Bluetooth LE** | Remote only: shutter, AF, record, bulb, zoom, focus, C1 (varies by brand). *No settings.* |
- | **Card → Google Drive** | md5-verified resumable offload, dedup, sorted by year and type |
- ## Requirements
- - Python 3.11+ and [uv](https://docs.astral.sh/uv/)
- - macOS is the main platform (it handles macOS's `ptpcamerad` grabbing the camera, and Bluetooth bond repair via
- `blueutil`). USB and Bluetooth control should also work on Linux; Windows is untested.
- - libgphoto2 comes bundled with the `gphoto2` Python wheels on macOS and Linux. On macOS the raw Sony client
- (`config explain`) uses the libusb bundled with them; on Linux install libusb-1.0 from your package manager.
- - Optional: [blueutil](https://github.com/toy/blueutil) (`brew install blueutil`) for stale Bluetooth bond repair;
- the Google Cloud CLI or a Google OAuth client for Drive offload.
- ## Install
- ```sh
- git clone https://github.com/jackulau/camctl.git && cd camctl
- uv sync
- uv run camctl doctor --fix # checks USB/BLE/Drive; frees the camera from macOS ptpcamerad
- ```
- Use as an MCP server (Claude Code shown; any MCP client works):
- ```sh
- claude mcp add camctl -- uv --directory /path/to/camctl run camctl-mcp
- ```
- ## Support matrix
- **USB / Wi-Fi PTP.** The vendor is detected automatically. Presets use canonical keys, and each vendor profile
- translates them.
- | Brand | Status | Camera-menu setup for USB control |
- |---|---|---|
- | Sony | **verified** on A7 V fw 1.01 | MENU → Network → Transfer/Remote → PC Remote Function → PC Remote: On, Cnct Method: USB |
- | Canon (EOS) | libgphoto2, untested on hardware | nothing to set; turn Wi-Fi/Bluetooth off (they block USB control) |
- | Nikon | libgphoto2, untested on hardware | SETUP → USB → MTP/PTP; Z bodies: Airplane mode on |
- | Fujifilm | libgphoto2, untested on hardware | SET UP → CONNECTION SETTING → PC CONNECTION MODE → USB TETHER SHOOTING AUTO |
- | Panasonic LUMIX | libgphoto2, untested on hardware | SETUP → IN/OUT → USB Mode → PC(Tether) |
- | OM System / Olympus | libgphoto2, untested on hardware | choose RAW/Control on the USB prompt (or USB Mode → RAW/Control) |
- Settings a brand doesn't have over USB are reported as `unsupported`. That is information, not a failure: apply and
- set still exit 0. Dial-owned or menu-only settings become on-camera checklist items. Locked settings say why (mode
- dial, white balance not on Color Temp, movie-only setting, Fujifilm dials not on A, ...).
- **Bluetooth LE remote** (`*` verified on hardware, `?` experimental):
- | Brand | Commands | Source |
- |---|---|---|
- | Sony | shoot\*, record\*, autofocus, focus, zoom, bulb, AF-ON, C1, with shutter/focus/record feedback | verified on A7 V |
- | Canon | shoot, autofocus, record, zoom? | Furble-confirmed protocol (BR-E1) |
- | Fujifilm | shoot, autofocus, bulb? | Furble-confirmed protocol |
- | Nikon | shoot, record?, bulb? | Furble-confirmed protocol (ML-L7) |
- | GoPro | shoot, record (shutter feedback) | Open GoPro spec |
- | Panasonic LUMIX | shoot?, record? | experimental |
- | OM System | none | recognised in scans, unsupported (no public protocol) |
- `camctl ble brands` prints this table from the code.
- ## Everyday use
- ```sh
- camctl doctor # everything at once; exit 1 on problems; --ble-scan, --json
- camctl status # vendor, model, battery, settings, card warnings, unsupported keys
- camctl preset list
- camctl preset apply photo # stills: M, RAW+JPEG, 1/250, f/2.8, Auto ISO, AF-C
- camctl preset apply cinematic-24 # video for grading: 4K24 10-bit 4:2:2, 1/50, 5600K
- camctl set shutter 1/125 iso 800
- camctl config dump # full backup → ~/.config/camctl/backups/
- camctl config load <file> --dry-run
- camctl config explain --filter movie # Sony: decode every property the camera reports
- camctl shoot -o captures/
- camctl offload --dry-run # card → Drive, md5 verified, sorted by year/type
- camctl drive organize # dry run: sort an existing archive; --apply to do it
- camctl calc shutter 24 # 180° rule → 1/50
- ```
- Built-in presets: `photo`, `photo-action`, `photo-group`, `cinematic-24`, `slowmo-60`, `easy-video`,
- `event-ceremony`, `outdoor-cinematic`, `talking-head`, `low-light`, `best-photo`, `best-cine-24`,
- `best-slowmo-60`, `best-slowmo-120`. Every apply backs up first and prints an on-camera checklist for what USB
- can't set. Save your own with `camctl preset save NAME`.
- `--json` works on every command (before or after the subcommand). Prompts and progress go to stderr.
- ### `camctl doctor`
- Read-only. It checks three things:
- - **USB:** whether a camera is connected, its vendor, model, firmware and battery, how many settings are writable,
- which are locked and why, which the brand doesn't support, and card warnings. With no camera, it runs the generic
- checks instead (data-capable cable, quit Image Capture/Photos/Imaging Edge, `--fix` stops ptpcamerad) and prints
- every vendor's USB setup.
- - **Bluetooth:** remembered cameras, the daemon, and blueutil. `--ble-scan` also listens for cameras.
- - **Drive:** whether auth works.
- It exits 0 when everything is fine and 1 on problems (no camera, camera won't open, card full, Bluetooth scan
- failing). Low battery, a nearly full card and missing Drive auth are warnings.
- ### Bluetooth
- ```sh
- camctl ble scan # every brand: brand, supported, pairing mode (--no-all-brands, --only canon)
- camctl ble pair # camera in pairing mode; press OK on the camera; verifies it survives reconnect
- camctl ble shoot [--no-af] [--hold S] [--burst S]
- camctl ble record [start|stop|toggle]
- camctl ble bulb 30 | focus in|out | zoom tele|wide [--seconds S --speed N] | af-on | autofocus | c1
- camctl ble status | devices | default ADDRESS | forget ADDRESS | brands
- camctl ble unpair ADDRESS [--clear-bond --allow-bt-restart]
- camctl ble serve # foreground daemon holding the link open
- ```
- `--address` and `--brand` pick a camera. The default is the remembered default camera, else the best scan hit.
- `ble shoot` reports `released`:
- - `true`: the camera confirmed the shot.
- - `false`: the camera reported it did *not* fire. Exits 1 with a hint such as "focus did not lock".
- - unknown: the brand has no shutter feedback. Exits 0 and prints a hint.
- `ble record` prints the camera's state, or a hint when the brand doesn't report it.
- **Daemon:** `camctl ble serve` keeps one camera connected on `~/.config/camctl/ble.sock`, reconnecting with
- backoff and sending GoPro keep-alives. Every other `ble` command and the MCP Bluetooth tools use it automatically,
- which makes shots near-instant. `--no-daemon` connects directly.
- **Stale bond repair:** if the camera forgot this Mac but macOS still holds the bond (CBError 14 "Peer removed
- pairing information"), pairing fails. `camctl ble pair --allow-bt-restart` clears the bond with blueutil by
- power-cycling Bluetooth. That briefly disconnects your other Bluetooth devices, so it only happens with the flag.
- Without the flag, the error prints the exact command, or the System Settings → Bluetooth → Forget This Device step.
- ## MCP tools
- - **Camera:** `camera_status` (vendor, every setting's value, writability, choices and locked reason, unsupported
- keys, card), `camera_doctor`, `set_settings`, presets, config dump/load/diff, `capture`, `record`,
- `liveview_jpeg`.
- - **Bluetooth:** `ble_scan`, `ble_pair` (`allow_bt_restart` defaults to false), `ble_shoot`, `ble_record`,
- `ble_command` (status/bulb/autofocus/zoom/focus/af_on/c1), `ble_devices`, `ble_brands`.
- - **Drive:** `offload`, `drive_organize`.
- - **Other:** calculators, and the `camctl://guide` resource that teaches the client how to use the rest.
- Bluetooth results carry the camera's prompts in `prompts`. The server never writes to stdout.
- ## Configuration
- Everything lives in `~/.config/camctl/`. None of it is required.
- | File | Purpose |
- |---|---|
- | `presets/*.yaml` | your own presets (`camctl preset save`) |
- | `backups/` | config dumps, written before every preset apply |
- | `ble.json` | remembered Bluetooth cameras |
- | `organize.yaml` | Drive archive folder names (see below) |
- | `sony_props.json` | optional property-name table for `config explain` (see below) |
- | `drive-credentials.json`, `drive-token.json` | Google OAuth client and token |
- Environment overrides: `CAMCTL_DRIVE_AUTH` (`gcloud` or `oauth`), `CAMCTL_DRIVE_TOKEN`,
- `CAMCTL_DRIVE_CREDENTIALS`, `CAMCTL_ORGANIZE_CONFIG`, `CAMCTL_SONY_PROPS`.
- **Property names.** `camctl config explain` decodes every property a Sony body reports, using camctl's own labels
- for the settings it knows and hex codes for the rest. To see a name for every code, supply your own
- `sony_props.json` mapping (`{"d157": {"name": "...", "values": {"1": "..."}}}`). No such table ships with camctl.
- ## Google Drive offload
- **Auth.** camctl uses the active gcloud account if it has Drive scope (`gcloud auth login
- --enable-gdrive-access`). Otherwise, put a Desktop OAuth client JSON (Drive API enabled) at
- `~/.config/camctl/drive-credentials.json` and run `camctl drive login`. Offload never deletes from the card. It
- prints `safe_to_format_card` only when every file is md5-verified on Drive.
- **Layout.** `camctl offload` uploads into one archive folder, "Card Archive", already sorted. md5 dedup spans the
- whole archive.
- ```text
- <YYYY>/Photos, <YYYY>/Videos phone and other photos/videos
- <YYYY>/Camera/RAW|JPEG|Videos camera DCIM/1xxXXXXX stills, Sony PRIVATE/M4ROOT clips with their XML
- Documents/… card folders you choose to keep whole (subpaths kept)
- Music/… audio, plus card folders you route there
- Other/<card path> everything else
- ```
- The year comes from EXIF, then a date in the file name, then the clip's XML, then the file's mtime.
- `--layout dated` keeps the older `<date>/<card>/<path>` layout instead.
- Choose which card folders are kept whole, and the music folder name, in `~/.config/camctl/organize.yaml`:
- ```yaml
- keep_folders: [Documents, Projects] # card top-level folders kept whole (case-insensitive)
- music_folder: Music
- music_sources: [Music, Audiobooks] # card folders whose whole contents go to music_folder
- ```
- Changing these on an existing archive changes what counts as already organized, so run a dry run first.
- **Organizing an existing archive.** `camctl drive organize` sorts folders that older offloads left behind
- (`<card>-<date>/…`, `<date>/<card>/…`) into this layout, and merges an older camera-only archive into it. Safety
- rules:
- - It is a dry run unless you pass `--apply`.
- - Applying only moves files; nothing is re-uploaded.
- - Duplicate copies (same md5) and emptied folders go to the Drive trash, recoverable for 30 days.
- - Afterwards it re-checks that every file is present exactly once, and logs to
- `~/.config/camctl/offload-logs/organize-*.jsonl`.
- - Re-running continues where it stopped, and it refuses to apply while an offload is running.
- ## Sony A7 V notes
- **One-time menu setup.** These can't be set over USB on firmware 1.01:
- 1. **Log Shooting: On (Flexible ISO), Color Gamut: S-Gamut3.Cine.** The A7 V has no S-Log picture profiles, and
- the Log property codes aren't advertised over USB: writes are acknowledged, then ignored.
- 2. **Different Set for Still/Mv: tick Aperture, Shutter, ISO, Exp. Comp, WB.** Otherwise photo and movie share
- exposure and white balance, so a video preset overwrites your photo settings.
- 3. **Mode dial → M.** Remote exposure-mode changes last only for the session; once unplugged, the dial rules.
- **Findings (verified on hardware):**
- - **Remote exposure mode:** `500e` is read-only until priority key `d25a` = 1 (PC Remote). After that, writing a
- raw `500e` code works (M = 1, Movie (M) = 491603). The named gphoto2 `expprogram` widget fails with "Bad
- parameters". Closing the session reverts to the dial, and exposure widgets unlock about 0.5 s after a mode change.
- - **Context locks:** `colortemperature` stays read-only until white balance is Color Temp. Movie SteadyShot
- (`d0da`) is read-only outside Movie mode. `status` and `doctor` say so instead of blaming the mode dial.
- - **libgphoto2 2.5.34 quirks:**
- - A full `get_config()` right after a write can segfault, so camctl reopens the session and re-asserts
- `d25a`/`500e`.
- - libgphoto2 drops Sony's 0xE000-range properties, so `sonyptp.py` is a raw pyusb Sony client used by
- `config explain`: Connect 1/2 → GetExtDeviceInfo 0x12C → Connect 3, GetAllExtDevicePropInfo 0x9209,
- SetExtDevicePropValue 0x9205.
- - **Capture** fails with `[-1] Unspecified error` when AF can't lock (lens cap on, too dark). Tethered captures
- download a 1616×1080 preview; the full RAW+JPEG is written to the card.
- - **Card access:** the card isn't visible in PC Remote mode. To offload, switch USB Connection to Mass Storage. A
- USB 2.0 cable caps reads at about 27 MB/s, so use a USB 3 cable or a card reader.
- - **Bluetooth:**
- - Service `8000FF00-FF00-FFFF-FFFF-FFFFFFFFFFFF`: write FF01, notify FF02.
- - Commands: half-press `0106/0107`, full press `0108/0109`, record `010E/010F`, AF-ON `0114/0115`, C1
- `0120/0121`, zoom `0244–0247` + step, focus `026A–026D` + step.
- - Status notifications: `02 3F|A0|D5 00|20`.
- - Pair once (MENU → Network → Bluetooth → Pairing, while `camctl ble pair` runs) and press OK on the camera.
- Otherwise the camera discards the bond at disconnect.
- **Other vendors.** Their profiles handle these quirks, taken from libgphoto2 sources and untested on hardware:
- - Canon: capturetarget → memory card; movie via live view plus `movierecordtarget`.
- - Nikon: live view and movie only on P/A/S/M, with the reason read from `liveviewprohibit`/`movieprohibit`.
- - Fujifilm: `prioritymode` → USB before exposure writes.
- - Panasonic: only Creative Video P/A/S/M over USB.
- ## Development
- ```sh
- uv sync
- uv run pytest # ~640 tests; no camera, Bluetooth or network needed
- uv run python scripts/live_check.py --capture # hardware smoke test, camera on USB (writes one still)
- ```
- The test suite fakes everything at the transport layer (gphoto2, bleak, blueutil, HTTP). A test that reaches real
- hardware or the network fails instead.
- ## Credits
- Non-Sony Bluetooth protocols come from [Furble](https://github.com/gkoh/furble) (MIT), thank you, and from GoPro's
- [Open GoPro](https://gopro.github.io/OpenGoPro) spec (Apache-2.0). USB control is built on
- [libgphoto2](http://www.gphoto.org/) through [python-gphoto2](https://github.com/jim-easterbrook/python-gphoto2).
- ## License
- [MIT](LICENSE).
- camctl is an independent project and is not affiliated with or endorsed by Sony, Canon, Nikon, Fujifilm,
- Panasonic, OM Digital Solutions or GoPro. All product names and trademarks belong to their owners. Changing
- camera settings and deleting or moving files is at your own risk. Keep backups.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.