Webcam MCP

🚀 Webcam MCP 📸

MCP server for webcam access - capture photos and video for LLM agents

Webcam MCP is a Model Context Protocol (MCP) server that allows LLM agents to directly access your webcam. It enables autonomous agents to capture photos and record video sequences, facilitating the debugging of cyberphysical systems, environmental monitoring, and interaction with the physical world without human intervention.

🚀 Quick Start

Installation

pip install webcam-mcp

Start the Server

webcam-mcp

By default, the server will start on http://0.0.0.0:8000/sse. You can test the server using any MCP client, for example, MCP Inspector (install via npx @modelcontextprotocol/inspector).

✨ Features

• 📸 High-Resolution Photos: Capture still images.
• 🎥 Video Recording: Record a sequence of frames over a specified duration.
• 🌐 Remote Access: SSE transport for network-accessible deployment.
• ⚙️ Configurable: Adjust resolution, camera index, and quality settings.
• 🔌 Cross-Platform: Works on Linux, macOS, and Windows.
• 🚀 Easy Integration: Simple MCP client configuration.

📦 Installation

pip install webcam-mcp

💻 Usage Examples

Basic Usage

# Start the server
webcam-mcp

Advanced Usage

# 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

CLI options

📚 Documentation

MCP Client Configuration

Claude Desktop

Add the following 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

🔧 Technical Details

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.

📄 License

This project is licensed under the MIT License - see the MIT License for details.