Skip to main content
Glama

camctl

Control your camera from the command line or from an AI assistant, with no vendor app. camctl is a CLI and an MCP 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

  • 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 (brew install blueutil) for stale Bluetooth bond repair; the Google Cloud CLI or a Google OAuth client for Drive offload.

Related MCP server: DaVinci Resolve MCP Server

Install

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

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

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

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.

<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:

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

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 (MIT), thank you, and from GoPro's Open GoPro spec (Apache-2.0). USB control is built on libgphoto2 through python-gphoto2.

License

MIT.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control DaVinci Resolve Studio through the official Scripting API, with full API coverage plus workflow helpers for editing, grading, Fusion, Fairlight, and project lifecycle tasks. Includes a compound tool mode for low context usage, a granular 341-tool mode, a local control panel, and an optional advanced offline server for working with Resolve project files.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to discover connected GoPro cameras and stream or sync videos directly to cloud storage such as Google Drive, Dropbox, OneDrive, or S3 with zero local disk usage.
      1
      MIT