Photo Shoot Planner

<p align="center"> <img src="assets/mascot/photo-scout.png" alt="Photo Shoot Planner mascot: a pixel-art photo scout bird carrying a camera and shoot plan" width="280"> </p>

A Claude-compatible MCP server and skill suite for both photography trips and professional photoshoot productions.

Two planning modes

Outdoor and astrophotography trips

• Resolve locations and normalize GPS coordinates
• Calculate moon phase, rise/set, altitude/azimuth, Milky Way core position, golden/blue hour, and astronomical darkness
• Review hourly cloud layers, visibility, wind, humidity, and precipitation
• Interpret supplied Bortle/SQM measurements without inventing site ratings
• Compare viewpoints, estimate routes, discover nearby lodging, and recommend camera settings

Managed photoshoot productions

• Convert the objective into a creative brief and visual direction
• Plan mood boards, locations, shot lists, talent, and crew
• Build budgets, equipment plans, wardrobe/prop manifests, and call sheets
• Track permits, insurance, model/property releases, and usage rights
• Run a final readiness gate before distributing the production book

Skill suite

The skills follow the modular pattern used by AI job-search collections: one coordinating workflow plus focused specialists that can trigger independently.

Skill	Responsibility
plan-photo-production	Coordinate the complete production book
develop-creative-brief	Objectives, audience, deliverables, usage, approvals
build-photo-mood-board	Visual references, palette, lighting, styling rules
scout-photo-location	Creative fit, light, access, permits, logistics, backup
create-photo-shot-list	Required coverage, setup grouping, priorities, timing
coordinate-talent-crew	Roles, bookings, responsibilities, travel, contacts
build-photo-call-sheet	Calls, schedule, meals, moves, weather, safety
manage-shoot-budget	Estimates, commitments, actuals, contingency, variance
plan-photo-equipment	Camera, lighting, grip, power, storage, redundancy
manage-wardrobe-props	Looks, props, products, continuity, returns
check-shoot-permits-releases	Permit/release/insurance issue spotting and status

MCP tools

Tool	Purpose
resolve_location	Convert a place name to candidate coordinates
get_astronomy	Daily sun/moon windows and phase
get_sky_timeline	Moon and Milky Way positions through a session
get_weather	Hourly shoot-condition forecast
assess_dark_sky	Interpret supplied Bortle or SQM data
compare_viewpoints	Rank candidate locations
plan_route	Estimate route distance and duration
find_nearby_lodging	Discover mapped lodging near a location
recommend_camera_settings	Gear-specific starting settings
calculate_shoot_budget	Calculate category totals, tax, contingency, and variance
build_call_sheet	Validate schedule math and person-level conflicts
generate_release_checklist	Generate a case-specific legal-readiness checklist
validate_shoot_readiness	Separate production blockers from warnings
create_shooting_plan	Produce a printable outdoor field plan

Install

Requires Node.js 20 or newer. First clone and build the project:

git clone https://github.com/chenyuan99/photo-shoot-planner.git
cd photo-shoot-planner
npm ci
npm run build

Install the skills in Codex

Codex discovers personal skills in ~/.agents/skills. Copying the skill folders there makes them available in every workspace.

macOS or Linux:

mkdir -p ~/.agents/skills
cp -R skills/. ~/.agents/skills/

Windows PowerShell:

New-Item -ItemType Directory -Force "$HOME/.agents/skills"
Copy-Item -Recurse -Force "skills/*" "$HOME/.agents/skills/"

For project-only installation, copy the folders to .agents/skills/ inside the target repository instead. Codex detects skill changes automatically; restart Codex if the new skills do not appear.

The skills can provide instruction-only planning after this step. Configure the MCP server below if you also want live location, weather, astronomy, routing, budget, call-sheet, and readiness tools.

Configure the MCP server

Run the server locally to verify the build:

npm test
npm start

To register the local server with Codex, replace the example path with the absolute path to this checkout:

codex mcp add photo-shoot-planner -- node /absolute/path/photo-shoot-planner/dist/index.js
codex mcp list

The ChatGPT desktop app, Codex CLI, and IDE extension share the Codex MCP configuration. Restart the active client after adding the server, then use /mcp to confirm it is connected.

For Claude Desktop development, configure the same absolute server path:

{
  "mcpServers": {
    "photo-shoot-planner": {
      "command": "node",
      "args": ["C:/absolute/path/photo-shoot-planner/dist/index.js"]
    }
  }
}

Use the skills

In Codex, run /skills or type $ in the prompt to browse installed skills. You can invoke a skill explicitly or describe the task naturally and let Codex choose the matching skill.

Use the coordinating skill for a complete professional production:

$plan-photo-production Plan a six-person editorial fashion shoot in Brooklyn on
September 18. The budget cap is $12,000. Produce the brief, shot list, crew plan,
budget, equipment list, call sheet, release checklist, and readiness report.

Invoke a specialist when you need one focused deliverable:

$build-photo-call-sheet Create a call sheet for a product shoot from 8:00 AM to
6:00 PM, with two studio setups, a 45-minute lunch, and a 30-minute strike.

$scout-photo-location Compare three locations for a golden-hour portrait shoot.
Evaluate creative fit, access, permits, weather risk, and a backup option.

Natural-language requests work too:

• "Compare Sequoia and Death Valley for Milky Way photography next weekend with a Nikon Z30."
• "Build a budget and equipment plan for a two-day commercial product shoot."
• "Audit this call sheet for timing conflicts, missing breaks, and readiness blockers."

For stronger results, include the shoot type, objective, date, location, deliverables, team size, budget, equipment constraints, usage rights, deadlines, and known safety or accessibility needs. Missing noncritical details can remain TBD with an owner and due date.

Package as a Claude extension

npm install -g @anthropic-ai/mcpb
npm run build
mcpb validate manifest.json
mcpb pack

Install the resulting .mcpb from Claude Desktop -> Settings -> Extensions -> Advanced settings -> Install Extension.

Data and safety notes

The server sends coordinates and search queries to Open-Meteo, OpenStreetMap Nominatim, OSRM, and Overpass. These public services may rate-limit or be unavailable. Astronomy calculations are local.

Forecasts, access, closures, permits, labor rules, insurance, usage rights, wildfire smoke, tides, lodging, and legal requirements must be verified with the relevant authority or qualified professional. Tool output is planning support, not legal, safety, labor, or insurance advice.

Schemas

Reusable contracts live in schemas/ for shooting plans, creative briefs, shot lists, budgets, and call sheets. Tool inputs are validated with Zod-generated JSON Schema.

License

MIT