jpcors/ring-mcp

Ring MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Ring home security devices. Control your Ring doorbells, cameras, lights, and alarm systems through MCP-compatible clients like Claude Desktop.

🚀 Features

• Device Management: List and get detailed information about all Ring devices
• Security Control: Arm/disarm Ring alarm systems with different modes
• Camera Operations: Capture snapshots from Ring cameras
• Light Control: Turn Ring lights on/off
• Real-time Monitoring: Monitor doorbell presses, motion detection, and other Ring events
• Smart Authentication: Automatic token management with multiple authentication methods
• Auto Token Updates: Maintains push notifications by automatically updating refresh tokens

📋 Prerequisites

• Node.js 18+ and npm
• Ring Account with Two-Factor Authentication (2FA) enabled
• MCP Client like Claude Desktop or other MCP-compatible applications

⚡ Quick Start

1. Installation

git clone https://github.com/jpcors/ring-mcp
cd ring-mcp-server
npm install
npm run build

2. First Run (Interactive Authentication)

npm start

On first run, the server will automatically prompt you to authenticate with Ring:

• Enter your Ring email and password
• Provide the 2FA code when prompted
• The server will save your refresh token automatically

3. Use with Claude Desktop

Add this to your Claude Desktop MCP configuration:

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

{
  "mcpServers": {
    "ring": {
      "command": "node",
      "args": ["/path/to/ring-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

🔐 Authentication Options

The server supports multiple authentication methods (checked in priority order):

Option 1: Command Line Token

npm start -- --token="your_refresh_token_here"

Option 2: Environment Variable

export RING_REFRESH_TOKEN="your_refresh_token"
npm start

Option 3: Automatic Config File

• Tokens are automatically saved to ring-config.json
• Updated tokens are automatically saved to maintain push notifications

Option 4: Interactive Authentication

• If no token is found, the server runs ring-auth-cli automatically
• Follow the prompts to enter your Ring credentials

Manual Authentication

# Generate token manually
npm run auth

# Then start server
npm start

🛠️ Available MCP Tools

Once connected to your MCP client, you can use these tools:

list_devices

Lists all Ring devices in your account with basic information.

get_device_info

Get detailed information about a specific Ring device.

• Parameters: deviceId (string)

arm_disarm_alarm

Control your Ring alarm system.

• Parameters:
  • locationId (string) - The location ID where the alarm is located
  • mode (string) - home, away, or disarmed

get_camera_snapshot

Capture a snapshot from a Ring camera.

• Parameters: deviceId (string) - The camera device ID

turn_light_on_off

Control Ring light devices.

• Parameters:
  • deviceId (string) - The light device ID
  • on (boolean) - true to turn on, false to turn off

monitor_events

Monitor real-time Ring events for a specified duration.

• Parameters: duration (number, optional) - Duration in seconds (default: 30)
• Returns: List of events including doorbell presses, motion detection, and notifications

⚙️ Configuration

Development Commands

npm run build     # Compile TypeScript
npm run dev       # Development mode with watch
npm start         # Start the MCP server
npm run auth      # Manual Ring authentication
npm run help      # Show usage help
npm test          # Run tests

Configuration Files

• ring-config.json - Automatically managed token storage
• .env - Optional environment variables
• package.json - Project dependencies and scripts
• tsconfig.json - TypeScript configuration

🔒 Security Considerations

• Token Security: Refresh tokens provide full access to your Ring account
• Local Storage: Tokens are stored locally in ring-config.json
• Auto-Updates: Tokens are automatically updated to maintain security
• Gitignore: Sensitive files are excluded from version control

Important Notes:

• Never share your refresh tokens
• The ring-config.json file contains sensitive authentication data
• Automatic token updates are critical for maintaining push notifications

🚨 Troubleshooting

Push Notifications Not Working

This usually means tokens aren't being updated properly:

1. Check if ring-config.json exists and has recent lastUpdated timestamp
2. Restart the server to trigger token refresh
3. If problems persist, delete ring-config.json and re-authenticate

Authentication Fails

1. Ensure 2FA is enabled on your Ring account
2. Check your email/password credentials
3. Verify you have an active internet connection
4. Try manual authentication: npm run auth

Device Not Found

1. Use list_devices to get correct device IDs
2. Ensure the device is online in the Ring app
3. Check that your Ring account has access to the device

MCP Connection Issues

1. Verify the path in your MCP client configuration
2. Ensure the server compiled successfully: npm run build
3. Check MCP client logs for connection errors

🔧 Development

Project Structure

src/
  index.ts          # Main MCP server implementation
package.json        # Dependencies and scripts
tsconfig.json       # TypeScript configuration
ring-config.json    # Auto-generated token storage
.env               # Optional environment variables

Key Architecture Components

• RingMCPServer: Main server class handling MCP protocol
• Token Management: Multi-tier authentication system
• Ring API Integration: Uses ring-client-api library
• Event Monitoring: Real-time Ring event subscriptions

Building and Testing

npm install           # Install dependencies
npm run build         # Compile TypeScript
npm run dev           # Development with watch mode
npm start -- --help   # Show usage options

⚠️ Disclaimer

This is an unofficial integration using the community-driven ring-client-api library. It is not affiliated with or endorsed by Ring/Amazon. Use at your own risk and in accordance with Ring's Terms of Service.

🙏 Acknowledgments

• dgreif/ring - The Ring API library
• Model Context Protocol - The MCP specification
• Ring community for reverse-engineering efforts