tapo-camera-mcp by sandraschi - MCP Server

Tapo Camera MCP Server

A FastMCP 2.12.0-compliant MCP server for TP-Link Tapo cameras, providing a unified interface for camera control and monitoring through the MCP protocol.

🏆 Gold Status Achievement

This project has achieved Gold Status on Glama.ai, the premier MCP server directory, with a perfect quality score of 85/100 points. This certification represents:

✅ Production Ready: Enterprise-grade MCP server
✅ Quality Validated: Comprehensive testing and documentation
✅ Security Compliant: Automated vulnerability scanning
✅ Professional Standards: Full CI/CD pipeline and structured logging

Platform Recognition: Featured in Glama.ai's directory of 5,000+ MCP servers with premium placement and enterprise credibility.

🚀 Features

📷 Supported Camera Types

Tapo Cameras: Full support for TP-Link Tapo series
Webcams: Basic support for local webcams
Ring Cameras: Experimental support for Ring devices
Furbo Cameras: Support for Furbo pet cameras

🎯 Core Features

Unified Camera Interface: Consistent API across different camera types
Modular Architecture: Easy to extend with new camera types and features
Asynchronous I/O: Built on asyncio for high performance
Type Annotations: Full type hints for better development experience

🎥 Camera Controls

Live Streaming: RTSP, RTMP, and HLS streaming support
PTZ Control: Pan, tilt, and zoom (where supported)
Motion Detection: Configurable motion detection settings
Snapshot Capture: Capture still images from video streams
Audio Support: Two-way audio where available

🔌 Integrations

Grafana Dashboards: Real-time monitoring and visualization
MCP 2.12.0 Protocol: Seamless integration with MCP ecosystem
REST API: HTTP endpoints for remote control and monitoring
Web Dashboard: Real-time video streaming interface

📺 Video Streaming Dashboard

Live Video Streams: Real-time MJPEG streaming from USB webcams
RTSP Integration: Direct streaming from Tapo cameras
Dynamic Camera Management: Add/remove cameras on the fly
Stream Controls: Start/stop streaming per camera
Responsive Design: Works on desktop and mobile browsers
Real-time Status: Live camera status and health monitoring
Snapshot Capture: Instant image capture from any camera
Multi-camera View: Grid layout for multiple camera feeds

🛠 Development Tools

CLI Interface: Command-line tools for administration
Mock Camera: Simulated camera for testing
Comprehensive Logging: Structured logging throughout codebase
Unit Tests: Complete test suite with 100% pass rate
CI/CD Pipeline: GitHub Actions with multi-version testing (Python 3.8-3.13)
Security Scanning: Automated vulnerability and dependency scanning
Code Quality: Black formatting, isort imports, mypy type checking, pylint linting

🚀 Getting Started

Prerequisites

Python 3.8 or higher
pip (Python package manager)
OpenCV (for webcam support)
TP-Link Tapo camera(s) or USB webcam

Installation

Install from source (recommended):

git clone https://github.com/yourusername/tapo-camera-mcp.git
cd tapo-camera-mcp
pip install -e .

Install dependencies:
```
pip install -r requirements.txt
```

Configuration

Copy the example configuration file:
```
cp config.example.yaml config.yaml
```

Edit config.yaml with your camera details:

cameras:
  living_room:
    type: tapo
    host: 192.168.1.100
    username: your_username
    password: your_password
  webcam:
    type: webcam
    device_id: 0

🚀 Usage

Starting the MCP Server

# Start MCP server for Claude Desktop integration
python -m tapo_camera_mcp.server_v2 --direct

# Start with debug logging
python -m tapo_camera_mcp.server_v2 --direct --debug

Starting the Web Dashboard

# Start the web dashboard (separate terminal)
python -m tapo_camera_mcp.web.server

# Dashboard will be available at: http://localhost:7777

Quick Start Script

# Check dependencies
python start.py check

# Test webcam
python start.py test

# Start MCP server only
python start.py mcp

# Start web dashboard only
python start.py dashboard

# Start both services
python start.py both

# Test webcam and start dashboard
python start.py webcam

Using the CLI

# List all available commands
tapo-camera-mcp --help

# Camera Management
tapo-camera-mcp camera list                   # List all cameras
tapo-camera-mcp camera status <camera_name>   # Get camera status
tapo-camera-mcp camera info <camera_name>     # Get detailed camera info

# PTZ Controls
tapo-camera-mcp camera ptz move --direction up --speed 0.5
tapo-camera-mcp camera ptz preset save --name "Home"
tapo-camera-mcp camera ptz preset goto --name "Home"

# Media Controls
tapo-camera-mcp camera snapshot               # Take a snapshot
tapo-camera-mcp camera record start           # Start recording
tapo-camera-mcp camera record stop            # Stop recording

# System Management
tapo-camera-mcp system status                # Check system status
tapo-camera-mcp system restart               # Restart the server
tapo-camera-mcp system update                # Update to the latest version

API Reference

Web Dashboard Endpoints

GET / - Main dashboard page
GET /api/cameras - Get list of all cameras
GET /api/cameras/{camera_id}/stream - Get video stream (MJPEG/RTSP)
GET /api/cameras/{camera_id}/snapshot - Get camera snapshot
GET /api/status - Get server status

MCP Tools

Camera Management

list_cameras - List all registered cameras
add_camera - Add a new camera to the system
connect_camera - Connect to a specific camera
disconnect_camera - Disconnect from camera
get_camera_info - Get detailed camera information
get_camera_status - Get camera status and health

PTZ Controls

move_ptz - Move PTZ camera (pan, tilt, zoom)
get_ptz_position - Get current PTZ position
save_ptz_preset - Save current position as preset
recall_ptz_preset - Move to saved preset position
go_to_home_ptz - Return to home position
stop_ptz - Stop PTZ movement

Media Operations

capture_image - Capture still image from camera
start_recording - Start video recording
stop_recording - Stop video recording
get_recording_status - Get recording status

System Management

get_system_info - Get camera system information
reboot_camera - Reboot the camera
get_logs - Get system logs
set_motion_detection - Configure motion detection
set_led_enabled - Control LED status
set_privacy_mode - Enable/disable privacy mode

🛠 Development

Project Structure

src/tapo_camera_mcp/
├── core/               # Core server implementation
├── camera/             # Camera implementations
│   ├── base.py         # Base camera class
│   ├── tapo.py         # Tapo camera implementation
│   └── ...
├── api/                # API endpoints
│   └── v1/             # API version 1
├── tools/              # MCP tools
│   ├── camera/         # Camera-related tools
│   ├── ptz/            # PTZ controls
│   └── system/         # System tools
├── web/                # Web interface
└── cli_v2.py           # Command-line interface

Setting Up Development Environment

Fork and clone the repository:

git clone https://github.com/yourusername/tapo-camera-mcp.git
cd tapo-camera-mcp

Create and activate a virtual environment:

# On Windows
python -m venv venv
.\venv\Scripts\activate

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

Install development dependencies:

pip install -e ".[dev]"
pre-commit install

Running Tests

# Run unit tests with coverage
pytest tests/unit/ --cov=tapo_camera_mcp --cov-report=html

# Run all tests
pytest tests/ -v

# Run MCP protocol tests
pytest tests/test_mcp_protocol.py

# Run with specific Python version (in CI/CD)
python -m pytest --cov=tapo_camera_mcp --cov-report=xml

Code Style

This project uses black for code formatting and isort for import sorting. Before committing, run:

black .
isort .
pylint tapo_camera_mcp/

License

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

Acknowledgments

TP-Link for their Tapo camera products
FastMCP for the MCP protocol implementation
aiohttp for the async HTTP client/server
ONVIF for the camera control protocol

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.