# OBSBOT Camera MCP Server
MCP (Model Context Protocol) server for PTZ camera control with gimbal positioning, snapshots, and AI visual analysis integration.
Designed for OBSBOT Tiny SE but works with any UVC PTZ camera that supports v4l2 controls.
## Features
- **Full Gimbal Control**: Pan, tilt, zoom with safety limits
- **Real-time Position Feedback**: Human-readable directions
- **Camera Snapshots**: High-resolution capture
- **Visual Analysis**: LM Studio integration for vision-language models
- **Area Scanning**: Horizontal, vertical, grid, and panoramic patterns
- **Autonomous Search**: Shell scripts for systematic exploration
- **Python Library**: Direct control for custom applications
## Requirements
### System
- Linux with v4l2 support
- Node.js 18+ (for MCP server)
- Python 3.8+ (for Python library)
### Packages
```bash
# Ubuntu/Debian
sudo apt install v4l-utils ffmpeg python3-opencv
# Fedora
sudo dnf install v4l-utils ffmpeg python3-opencv
```
### Optional
- [LM Studio](https://lmstudio.ai/) for visual analysis
- Vision-language model (e.g., Qwen2.5-VL, LLaVA)
## Installation
### MCP Server
```bash
cd obsbot-camera-mcp
npm install
```
### Python Library
```bash
pip install opencv-python
```
## Configuration
### Environment Variables
```bash
export OBSBOT_DEVICE="/dev/video0" # Camera device
export OBSBOT_OUTPUT_DIR="/tmp/obsbot" # Capture directory
export LM_STUDIO_URL="http://localhost:1234/v1/chat/completions"
export OBSBOT_VL_MODEL="qwen2.5-vl-7b-instruct"
```
### Claude Desktop Configuration
Add to `~/.config/claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"obsbot": {
"command": "node",
"args": ["/path/to/obsbot-camera-mcp/src/obsbot-mcp-server.mjs"],
"env": {
"OBSBOT_DEVICE": "/dev/video0"
}
}
}
}
```
## Usage
### MCP Server Tools
#### get_gimbal_position
Get current pan, tilt, zoom with readable directions.
#### control_gimbal
Move gimbal to absolute position.
- Pan: -468000 (right) to 468000 (left)
- Tilt: -324000 (down) to 324000 (up)
- Zoom: 0 (wide) to 12 (telephoto)
#### center_camera
Return to neutral position (0, 0, 0).
#### take_snapshot
Capture image with optional LM Studio analysis.
```json
{
"analyzeWithLM": true,
"customPrompt": "Describe what you see"
}
```
#### look_and_analyze
Move camera and take analyzed snapshot in one operation.
#### scan_area
Systematic multi-position scan.
```json
{
"pattern": "horizontal", // or vertical, grid, panoramic
"steps": 5
}
```
#### check_system_status
Verify camera and LM Studio availability.
### Python Library
```python
from python.obsbot_control import OBSBOTController
camera = OBSBOTController()
camera.connect()
# Move to position
camera.set_position(pan=200000, tilt=100000, zoom=2)
# Use presets
camera.preset_position("left")
camera.preset_position("center")
# Capture
camera.save_frame("snapshot.jpg")
# Scan
results = camera.scan_horizontal(steps=5, capture=True)
camera.disconnect()
```
### Shell Script
```bash
# Basic search
./scripts/autonomous_scan.sh "find the window"
# Grid pattern with verbose output
./scripts/autonomous_scan.sh --pattern grid --verbose "locate books"
# Quick scan
./scripts/autonomous_scan.sh --pattern quick "identify objects"
```
## Camera Compatibility
Tested with:
- OBSBOT Tiny SE
- OBSBOT Meet
Should work with any UVC PTZ camera supporting:
- `pan_absolute` control
- `tilt_absolute` control
- `zoom_absolute` control
Check your camera's controls:
```bash
v4l2-ctl -d /dev/video0 --list-ctrls
```
## Gimbal Directions
The v4l2 control values map to directions:
- **Pan**: Positive = LEFT, Negative = RIGHT
- **Tilt**: Positive = UP, Negative = DOWN
- **Zoom**: Higher = telephoto (zoomed in)
## Troubleshooting
### Camera not found
```bash
v4l2-ctl --list-devices
ls -la /dev/video*
```
### Permission denied
```bash
sudo usermod -a -G video $USER
# Logout and login again
```
### Controls not working
```bash
# Check available controls
v4l2-ctl -d /dev/video0 --list-ctrls
# Test manual control
v4l2-ctl -d /dev/video0 --set-ctrl=pan_absolute=100000
```
## License
MIT License - See LICENSE file
## Related Projects
- [sam-angle-detection](https://github.com/Radar105/sam-angle-detection) - SAM-based angle measurement
- [openwebui-anthropic-pipe](https://github.com/Radar105/openwebui-anthropic-pipe) - Anthropic API pipe for Open WebUI
