Skip to content
Back to search

camctl

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jackulau--camctl/badge.svg)](/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
  1. # camctl
  2. Control your camera from the command line or from an AI assistant, with no vendor app. camctl is a CLI and an
  3. [MCP](https://modelcontextprotocol.io) server that changes settings, applies presets, shoots, records, runs live
  4. view, acts as a Bluetooth remote, and offloads cards to Google Drive with md5 verification.
  5. It was built and verified on a **Sony A7 V (ILCE-7M5)**. Canon, Nikon, Fujifilm, Panasonic and OM System are
  6. supported through libgphoto2 and published Bluetooth protocols, but are **untested on hardware**. Reports and fixes
  7. from owners are welcome.
  8. | Transport | What works |
  9. |---|---|
  10. | **USB-C (PTP)** | Every setting the camera exposes: presets, dump/load/diff config, capture, record, live view |
  11. | **Wi-Fi (PTP/IP)** | Same as USB via `--port ptpip:<camera IP>` (Sony: PC Remote Cnct Method: Wi-Fi) |
  12. | **Bluetooth LE** | Remote only: shutter, AF, record, bulb, zoom, focus, C1 (varies by brand). *No settings.* |
  13. | **Card → Google Drive** | md5-verified resumable offload, dedup, sorted by year and type |
  14. ## Requirements
  15. - Python 3.11+ and [uv](https://docs.astral.sh/uv/)
  16. - macOS is the main platform (it handles macOS's `ptpcamerad` grabbing the camera, and Bluetooth bond repair via
  17. `blueutil`). USB and Bluetooth control should also work on Linux; Windows is untested.
  18. - libgphoto2 comes bundled with the `gphoto2` Python wheels on macOS and Linux. On macOS the raw Sony client
  19. (`config explain`) uses the libusb bundled with them; on Linux install libusb-1.0 from your package manager.
  20. - Optional: [blueutil](https://github.com/toy/blueutil) (`brew install blueutil`) for stale Bluetooth bond repair;
  21. the Google Cloud CLI or a Google OAuth client for Drive offload.
  22. ## Install
  23. ```sh
  24. git clone https://github.com/jackulau/camctl.git && cd camctl
  25. uv sync
  26. uv run camctl doctor --fix # checks USB/BLE/Drive; frees the camera from macOS ptpcamerad
  27. ```
  28. Use as an MCP server (Claude Code shown; any MCP client works):
  29. ```sh
  30. claude mcp add camctl -- uv --directory /path/to/camctl run camctl-mcp
  31. ```
  32. ## Support matrix
  33. **USB / Wi-Fi PTP.** The vendor is detected automatically. Presets use canonical keys, and each vendor profile
  34. translates them.
  35. | Brand | Status | Camera-menu setup for USB control |
  36. |---|---|---|
  37. | Sony | **verified** on A7 V fw 1.01 | MENU → Network → Transfer/Remote → PC Remote Function → PC Remote: On, Cnct Method: USB |
  38. | Canon (EOS) | libgphoto2, untested on hardware | nothing to set; turn Wi-Fi/Bluetooth off (they block USB control) |
  39. | Nikon | libgphoto2, untested on hardware | SETUP → USB → MTP/PTP; Z bodies: Airplane mode on |
  40. | Fujifilm | libgphoto2, untested on hardware | SET UP → CONNECTION SETTING → PC CONNECTION MODE → USB TETHER SHOOTING AUTO |
  41. | Panasonic LUMIX | libgphoto2, untested on hardware | SETUP → IN/OUT → USB Mode → PC(Tether) |
  42. | OM System / Olympus | libgphoto2, untested on hardware | choose RAW/Control on the USB prompt (or USB Mode → RAW/Control) |
  43. Settings a brand doesn't have over USB are reported as `unsupported`. That is information, not a failure: apply and
  44. set still exit 0. Dial-owned or menu-only settings become on-camera checklist items. Locked settings say why (mode
  45. dial, white balance not on Color Temp, movie-only setting, Fujifilm dials not on A, ...).
  46. **Bluetooth LE remote** (`*` verified on hardware, `?` experimental):
  47. | Brand | Commands | Source |
  48. |---|---|---|
  49. | Sony | shoot\*, record\*, autofocus, focus, zoom, bulb, AF-ON, C1, with shutter/focus/record feedback | verified on A7 V |
  50. | Canon | shoot, autofocus, record, zoom? | Furble-confirmed protocol (BR-E1) |
  51. | Fujifilm | shoot, autofocus, bulb? | Furble-confirmed protocol |
  52. | Nikon | shoot, record?, bulb? | Furble-confirmed protocol (ML-L7) |
  53. | GoPro | shoot, record (shutter feedback) | Open GoPro spec |
  54. | Panasonic LUMIX | shoot?, record? | experimental |
  55. | OM System | none | recognised in scans, unsupported (no public protocol) |
  56. `camctl ble brands` prints this table from the code.
  57. ## Everyday use
  58. ```sh
  59. camctl doctor # everything at once; exit 1 on problems; --ble-scan, --json
  60. camctl status # vendor, model, battery, settings, card warnings, unsupported keys
  61. camctl preset list
  62. camctl preset apply photo # stills: M, RAW+JPEG, 1/250, f/2.8, Auto ISO, AF-C
  63. camctl preset apply cinematic-24 # video for grading: 4K24 10-bit 4:2:2, 1/50, 5600K
  64. camctl set shutter 1/125 iso 800
  65. camctl config dump # full backup → ~/.config/camctl/backups/
  66. camctl config load <file> --dry-run
  67. camctl config explain --filter movie # Sony: decode every property the camera reports
  68. camctl shoot -o captures/
  69. camctl offload --dry-run # card → Drive, md5 verified, sorted by year/type
  70. camctl drive organize # dry run: sort an existing archive; --apply to do it
  71. camctl calc shutter 24 # 180° rule → 1/50
  72. ```
  73. Built-in presets: `photo`, `photo-action`, `photo-group`, `cinematic-24`, `slowmo-60`, `easy-video`,
  74. `event-ceremony`, `outdoor-cinematic`, `talking-head`, `low-light`, `best-photo`, `best-cine-24`,
  75. `best-slowmo-60`, `best-slowmo-120`. Every apply backs up first and prints an on-camera checklist for what USB
  76. can't set. Save your own with `camctl preset save NAME`.
  77. `--json` works on every command (before or after the subcommand). Prompts and progress go to stderr.
  78. ### `camctl doctor`
  79. Read-only. It checks three things:
  80. - **USB:** whether a camera is connected, its vendor, model, firmware and battery, how many settings are writable,
  81. which are locked and why, which the brand doesn't support, and card warnings. With no camera, it runs the generic
  82. checks instead (data-capable cable, quit Image Capture/Photos/Imaging Edge, `--fix` stops ptpcamerad) and prints
  83. every vendor's USB setup.
  84. - **Bluetooth:** remembered cameras, the daemon, and blueutil. `--ble-scan` also listens for cameras.
  85. - **Drive:** whether auth works.
  86. It exits 0 when everything is fine and 1 on problems (no camera, camera won't open, card full, Bluetooth scan
  87. failing). Low battery, a nearly full card and missing Drive auth are warnings.
  88. ### Bluetooth
  89. ```sh
  90. camctl ble scan # every brand: brand, supported, pairing mode (--no-all-brands, --only canon)
  91. camctl ble pair # camera in pairing mode; press OK on the camera; verifies it survives reconnect
  92. camctl ble shoot [--no-af] [--hold S] [--burst S]
  93. camctl ble record [start|stop|toggle]
  94. camctl ble bulb 30 | focus in|out | zoom tele|wide [--seconds S --speed N] | af-on | autofocus | c1
  95. camctl ble status | devices | default ADDRESS | forget ADDRESS | brands
  96. camctl ble unpair ADDRESS [--clear-bond --allow-bt-restart]
  97. camctl ble serve # foreground daemon holding the link open
  98. ```
  99. `--address` and `--brand` pick a camera. The default is the remembered default camera, else the best scan hit.
  100. `ble shoot` reports `released`:
  101. - `true`: the camera confirmed the shot.
  102. - `false`: the camera reported it did *not* fire. Exits 1 with a hint such as "focus did not lock".
  103. - unknown: the brand has no shutter feedback. Exits 0 and prints a hint.
  104. `ble record` prints the camera's state, or a hint when the brand doesn't report it.
  105. **Daemon:** `camctl ble serve` keeps one camera connected on `~/.config/camctl/ble.sock`, reconnecting with
  106. backoff and sending GoPro keep-alives. Every other `ble` command and the MCP Bluetooth tools use it automatically,
  107. which makes shots near-instant. `--no-daemon` connects directly.
  108. **Stale bond repair:** if the camera forgot this Mac but macOS still holds the bond (CBError 14 "Peer removed
  109. pairing information"), pairing fails. `camctl ble pair --allow-bt-restart` clears the bond with blueutil by
  110. power-cycling Bluetooth. That briefly disconnects your other Bluetooth devices, so it only happens with the flag.
  111. Without the flag, the error prints the exact command, or the System Settings → Bluetooth → Forget This Device step.
  112. ## MCP tools
  113. - **Camera:** `camera_status` (vendor, every setting's value, writability, choices and locked reason, unsupported
  114. keys, card), `camera_doctor`, `set_settings`, presets, config dump/load/diff, `capture`, `record`,
  115. `liveview_jpeg`.
  116. - **Bluetooth:** `ble_scan`, `ble_pair` (`allow_bt_restart` defaults to false), `ble_shoot`, `ble_record`,
  117. `ble_command` (status/bulb/autofocus/zoom/focus/af_on/c1), `ble_devices`, `ble_brands`.
  118. - **Drive:** `offload`, `drive_organize`.
  119. - **Other:** calculators, and the `camctl://guide` resource that teaches the client how to use the rest.
  120. Bluetooth results carry the camera's prompts in `prompts`. The server never writes to stdout.
  121. ## Configuration
  122. Everything lives in `~/.config/camctl/`. None of it is required.
  123. | File | Purpose |
  124. |---|---|
  125. | `presets/*.yaml` | your own presets (`camctl preset save`) |
  126. | `backups/` | config dumps, written before every preset apply |
  127. | `ble.json` | remembered Bluetooth cameras |
  128. | `organize.yaml` | Drive archive folder names (see below) |
  129. | `sony_props.json` | optional property-name table for `config explain` (see below) |
  130. | `drive-credentials.json`, `drive-token.json` | Google OAuth client and token |
  131. Environment overrides: `CAMCTL_DRIVE_AUTH` (`gcloud` or `oauth`), `CAMCTL_DRIVE_TOKEN`,
  132. `CAMCTL_DRIVE_CREDENTIALS`, `CAMCTL_ORGANIZE_CONFIG`, `CAMCTL_SONY_PROPS`.
  133. **Property names.** `camctl config explain` decodes every property a Sony body reports, using camctl's own labels
  134. for the settings it knows and hex codes for the rest. To see a name for every code, supply your own
  135. `sony_props.json` mapping (`{"d157": {"name": "...", "values": {"1": "..."}}}`). No such table ships with camctl.
  136. ## Google Drive offload
  137. **Auth.** camctl uses the active gcloud account if it has Drive scope (`gcloud auth login
  138. --enable-gdrive-access`). Otherwise, put a Desktop OAuth client JSON (Drive API enabled) at
  139. `~/.config/camctl/drive-credentials.json` and run `camctl drive login`. Offload never deletes from the card. It
  140. prints `safe_to_format_card` only when every file is md5-verified on Drive.
  141. **Layout.** `camctl offload` uploads into one archive folder, "Card Archive", already sorted. md5 dedup spans the
  142. whole archive.
  143. ```text
  144. <YYYY>/Photos, <YYYY>/Videos phone and other photos/videos
  145. <YYYY>/Camera/RAW|JPEG|Videos camera DCIM/1xxXXXXX stills, Sony PRIVATE/M4ROOT clips with their XML
  146. Documents/… card folders you choose to keep whole (subpaths kept)
  147. Music/… audio, plus card folders you route there
  148. Other/<card path> everything else
  149. ```
  150. The year comes from EXIF, then a date in the file name, then the clip's XML, then the file's mtime.
  151. `--layout dated` keeps the older `<date>/<card>/<path>` layout instead.
  152. Choose which card folders are kept whole, and the music folder name, in `~/.config/camctl/organize.yaml`:
  153. ```yaml
  154. keep_folders: [Documents, Projects] # card top-level folders kept whole (case-insensitive)
  155. music_folder: Music
  156. music_sources: [Music, Audiobooks] # card folders whose whole contents go to music_folder
  157. ```
  158. Changing these on an existing archive changes what counts as already organized, so run a dry run first.
  159. **Organizing an existing archive.** `camctl drive organize` sorts folders that older offloads left behind
  160. (`<card>-<date>/…`, `<date>/<card>/…`) into this layout, and merges an older camera-only archive into it. Safety
  161. rules:
  162. - It is a dry run unless you pass `--apply`.
  163. - Applying only moves files; nothing is re-uploaded.
  164. - Duplicate copies (same md5) and emptied folders go to the Drive trash, recoverable for 30 days.
  165. - Afterwards it re-checks that every file is present exactly once, and logs to
  166. `~/.config/camctl/offload-logs/organize-*.jsonl`.
  167. - Re-running continues where it stopped, and it refuses to apply while an offload is running.
  168. ## Sony A7 V notes
  169. **One-time menu setup.** These can't be set over USB on firmware 1.01:
  170. 1. **Log Shooting: On (Flexible ISO), Color Gamut: S-Gamut3.Cine.** The A7 V has no S-Log picture profiles, and
  171. the Log property codes aren't advertised over USB: writes are acknowledged, then ignored.
  172. 2. **Different Set for Still/Mv: tick Aperture, Shutter, ISO, Exp. Comp, WB.** Otherwise photo and movie share
  173. exposure and white balance, so a video preset overwrites your photo settings.
  174. 3. **Mode dial → M.** Remote exposure-mode changes last only for the session; once unplugged, the dial rules.
  175. **Findings (verified on hardware):**
  176. - **Remote exposure mode:** `500e` is read-only until priority key `d25a` = 1 (PC Remote). After that, writing a
  177. raw `500e` code works (M = 1, Movie (M) = 491603). The named gphoto2 `expprogram` widget fails with "Bad
  178. parameters". Closing the session reverts to the dial, and exposure widgets unlock about 0.5 s after a mode change.
  179. - **Context locks:** `colortemperature` stays read-only until white balance is Color Temp. Movie SteadyShot
  180. (`d0da`) is read-only outside Movie mode. `status` and `doctor` say so instead of blaming the mode dial.
  181. - **libgphoto2 2.5.34 quirks:**
  182. - A full `get_config()` right after a write can segfault, so camctl reopens the session and re-asserts
  183. `d25a`/`500e`.
  184. - libgphoto2 drops Sony's 0xE000-range properties, so `sonyptp.py` is a raw pyusb Sony client used by
  185. `config explain`: Connect 1/2 → GetExtDeviceInfo 0x12C → Connect 3, GetAllExtDevicePropInfo 0x9209,
  186. SetExtDevicePropValue 0x9205.
  187. - **Capture** fails with `[-1] Unspecified error` when AF can't lock (lens cap on, too dark). Tethered captures
  188. download a 1616×1080 preview; the full RAW+JPEG is written to the card.
  189. - **Card access:** the card isn't visible in PC Remote mode. To offload, switch USB Connection to Mass Storage. A
  190. USB 2.0 cable caps reads at about 27 MB/s, so use a USB 3 cable or a card reader.
  191. - **Bluetooth:**
  192. - Service `8000FF00-FF00-FFFF-FFFF-FFFFFFFFFFFF`: write FF01, notify FF02.
  193. - Commands: half-press `0106/0107`, full press `0108/0109`, record `010E/010F`, AF-ON `0114/0115`, C1
  194. `0120/0121`, zoom `0244–0247` + step, focus `026A–026D` + step.
  195. - Status notifications: `02 3F|A0|D5 00|20`.
  196. - Pair once (MENU → Network → Bluetooth → Pairing, while `camctl ble pair` runs) and press OK on the camera.
  197. Otherwise the camera discards the bond at disconnect.
  198. **Other vendors.** Their profiles handle these quirks, taken from libgphoto2 sources and untested on hardware:
  199. - Canon: capturetarget → memory card; movie via live view plus `movierecordtarget`.
  200. - Nikon: live view and movie only on P/A/S/M, with the reason read from `liveviewprohibit`/`movieprohibit`.
  201. - Fujifilm: `prioritymode` → USB before exposure writes.
  202. - Panasonic: only Creative Video P/A/S/M over USB.
  203. ## Development
  204. ```sh
  205. uv sync
  206. uv run pytest # ~640 tests; no camera, Bluetooth or network needed
  207. uv run python scripts/live_check.py --capture # hardware smoke test, camera on USB (writes one still)
  208. ```
  209. The test suite fakes everything at the transport layer (gphoto2, bleak, blueutil, HTTP). A test that reaches real
  210. hardware or the network fails instead.
  211. ## Credits
  212. Non-Sony Bluetooth protocols come from [Furble](https://github.com/gkoh/furble) (MIT), thank you, and from GoPro's
  213. [Open GoPro](https://gopro.github.io/OpenGoPro) spec (Apache-2.0). USB control is built on
  214. [libgphoto2](http://www.gphoto.org/) through [python-gphoto2](https://github.com/jim-easterbrook/python-gphoto2).
  215. ## License
  216. [MIT](LICENSE).
  217. camctl is an independent project and is not affiliated with or endorsed by Sony, Canon, Nikon, Fujifilm,
  218. Panasonic, OM Digital Solutions or GoPro. All product names and trademarks belong to their owners. Changing
  219. camera settings and deleting or moving files is at your own risk. Keep backups.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.