Webcam MCP

Fork notice. This is botbridge-webcam-mcp, a fork of pavel-kirienko/webcam_mcp (MIT), maintained by 1019666077-bit. It adds an MCP Apps panel (webcam_panel). Install this distribution as botbridge-webcam-mcp; the upstream distribution on PyPI is named webcam-mcp. The Python import package is webcam_mcp.

---

Webcam MCP is a Model Context Protocol (MCP) server that gives LLM agents direct access to your webcam. It enables autonomous agents to capture photos and record video sequences, making it possible to debug cyberphysical systems, monitor environments, and interact with the physical world without human intervention.

Features:

• 📸 High-Resolution Photos: Capture still images
• 🎛️ MCP Apps panel (webcam_panel): Free in-chat buttons (拍一张 / 再拍 / 关掉); Pro placeholders only
• 🎥 Video Recording: Record a sequence of frames over a specified duration
• 🌐 SSE transport: loopback by default; LAN exposure is opt-in and unauthenticated
• ⚙️ Configurable: Adjust resolution, camera index, and quality settings
• 🔌 Cross-Platform: Works on Linux, macOS, and Windows
• 🚀 Easy Integration: Simple MCP client configuration

Usage

Install:

pip install botbridge-webcam-mcp

Start the MCP server:

webcam-mcp

The server starts on http://127.0.0.1:8000/sse by default (loopback only).

You can test the server using any MCP client, e.g., MCP Inspector (install via npx @modelcontextprotocol/inspector).

CLI options

Option	Type	Default	Description
--host	string	127.0.0.1	Server host address
--port	integer	8000	Server port
--camera-index	integer	0	Webcam device index
--photo-width	integer	1920	Default photo width in pixels
--photo-height	integer	1080	Default photo height in pixels
--video-width	integer	640	Default video frame width in pixels
--video-height	integer	480	Default video frame height in pixels
--version	-	-	Show version and exit

Examples

# Start on custom port
webcam-mcp --port 9000

# Use different camera (e.g., external USB webcam)
webcam-mcp --camera-index 1

# Custom photo resolution
webcam-mcp --photo-width 1280 --photo-height 720

# Opt-in LAN exposure (unauthenticated! see Security below)
WEBCAM_MCP_ALLOW_LAN=1 webcam-mcp --host 0.0.0.0

Security

The SSE transport has no authentication. Anyone who can reach the SSE endpoint can trigger your webcam to take photos and record video.

• Prefer stdio (desktop MCP clients use it automatically) or loopback (127.0.0.1, the default).
• Binding --host to a non-loopback address (e.g. 0.0.0.0 or a LAN IP) prints a loud warning at startup and is refused unless you set WEBCAM_MCP_ALLOW_LAN=1.
• Only expose the server on your LAN or a public interface if you understand the risk and have your own authentication in front of it.

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "webcam": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Location of config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Other MCP Clients

Any MCP client supporting SSE transport can connect to:

http://<host>:<port>/sse

MCP Tools

take_photo

Captures a single high-resolution photo from the webcam.

Parameters: None

Returns: JPEG image

Example usage in Claude:

Can you take a photo and describe what you see?

record_video

Records video frames over a specified duration.

Parameters:

• duration_seconds (float, optional): Recording duration in seconds
  • Minimum: 1.0 second
  • Maximum: 60.0 seconds
  • Default: 5.0 seconds

Returns: List of JPEG frames

Example usage in Claude:

Record a 10-second video and analyze any movement you detect.

Troubleshooting

Camera Permission Denied (macOS)

On macOS, you need to grant camera permissions:

1. Open System Settings → Privacy & Security → Camera
2. Enable camera access for Terminal (or your terminal app)
3. Restart the terminal and try again

Camera Already in Use

If you see "Camera unavailable" errors:

1. Close other applications using the webcam (Zoom, Skype, etc.)
2. Check if another instance of webcam-mcp is running
3. Try a different camera index: webcam-mcp --camera-index 1

Wrong Camera Index

To find available cameras:

import cv2
for i in range(10):
    cap = cv2.VideoCapture(i)
    if cap.isOpened():
        print(f"Camera {i}: Available")
        cap.release()
    else:
        print(f"Camera {i}: Not available")

Then use --camera-index with the correct number.

Resolution Not Supported

If your camera doesn't support the requested resolution, the server will:

• Log a warning with the actual resolution achieved
• Continue operating with the camera's maximum supported resolution

Check logs for messages like:

WARNING: Requested resolution 1920x1080, but camera provided 1280x720

Development

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_camera.py

All tests use mocked camera hardware, so no physical webcam is required for testing.

Release

To tag and release a new version, push a new commit to main with a new __version__ string. This will trigger a new tag and a new release push to PyPI.