viper-marketplace

Viper Claude Plugin Marketplace

This repository is a Claude Code marketplace source for Viper-related plugins. It currently publishes one installable plugin, viper-redteam, built around the current public Viper MCP tool surface.

Repository Layout

• .claude-plugin/marketplace.json defines this repository as a marketplace source.
• plugins/viper-redteam/ contains the installable Claude Code plugin.
• plugins/viper-redteam/.claude-plugin/plugin.json defines the plugin metadata.
• plugins/viper-redteam/.mcp.json defines the remote SSE MCP connection template.
• plugins/viper-redteam/skills/ contains workflow skills.
• plugins/viper-redteam/agents/ contains higher-level task agents.
• docs/ contains supplementary notes.

Included Plugin

viper-redteam

viper-redteam is a Claude Code plugin for internal red team assessment and threat simulation against a remote Viper MCP server.

It adds:

• a remote SSE MCP connection template for Viper
• four workflow skills aligned to the current public tool surface
• two agents for multi-step operational work

Current MCP Tool Surface

The plugin is intentionally limited to the tools currently exposed by the Viper MCP server.

Current public tools:

• get_host_info
• get_session_info
• list_handler
• list_session
• list_host
• list_route
• query_route_by_ipaddress
• query_port_forward_config
• session_meterpreter_command_run
• session_shell_command_run
• read_loot_file
• msf_module_execute
• msf_module_search
• msf_module_info
• msf_module_target_compatible_payloads

The plugin does not package functions that exist elsewhere in the Viper codebase but are not currently registered in the active MCP tool surface.

Installation

1. Start the remote Viper MCP server

Run Worker/mcpserver.py on the Viper host. On startup it prints an SSE URL in this form:

http://your_server_ip:8000/<uuid>/sse

You can use either HTTP or HTTPS for the endpoint. If your environment supports it, HTTPS is recommended.

2. Set VIPER_MCP_SSE_URL on the Claude Code client

Set the environment variable on the machine where Claude Code runs.

PowerShell:

$env:VIPER_MCP_SSE_URL = "https://viper.example.com/abcd1234efgh5678/sse"

Bash:

export VIPER_MCP_SSE_URL="https://viper.example.com/abcd1234efgh5678/sse"

The UUID segment must match the value printed by mcpserver.py.

3. Install the plugin

Use one of these approaches:

• Install plugins/viper-redteam directly as a local Claude Code plugin directory.
• Register this repository as a Claude Code marketplace source and install viper-redteam from the marketplace index.

4. Verify MCP connectivity

Inside Claude Code:

1. Run /mcp.
2. Confirm the viper server appears.
3. Confirm the exposed tools match the plugin scope.

Architecture Boundary

The plugin follows the current Viper MCP boundary:

• Worker/mcpserver.py is the transport and registration layer.
• The Viper MCP server exposes the current tool surface.
• Claude Code plugin components handle workflow composition and operator guidance.
• The plugin connects to Viper remotely through SSE; it does not try to start Viper locally.

Operational Model

The plugin separates responsibilities across skills and agents.

Skills

• internal-recon builds a current view of hosts, sessions, routes, pivots, and reachable coverage.
• session-operations operates within existing sessions and handles command execution and evidence collection.
• threat-simulation supports module search, option review, payload compatibility checks, handler checks, and execution planning.
• reporting turns Viper MCP output into concise operational summaries, evidence snapshots, and next-step reporting.

Agents

• redteam-operator handles end-to-end internal red team tasks that span discovery, session inspection, and controlled operational sequencing.
• threat-simulation-planner handles Metasploit-oriented module validation, payload review, handler readiness, and staged execution planning.

Troubleshooting

If the server does not appear in /mcp:

• Verify VIPER_MCP_SSE_URL is set in the shell that launched Claude Code.
• Verify the remote URL is reachable from the Claude Code client.
• Verify the UUID path matches the value printed by mcpserver.py.
• Verify any reverse proxy forwards the required SSE and message paths.

If the server appears but tool calls fail:

• Confirm the remote Viper instance is healthy.
• Confirm RPC and database dependencies on the Viper host are working.
• Confirm the target session, host, route, or module identifiers are valid for the current environment.

Marketplace Metadata

• Marketplace source: .claude-plugin/marketplace.json
• Plugin package: plugins/viper-redteam/
• Plugin manifest: plugins/viper-redteam/.claude-plugin/plugin.json
• MCP config: plugins/viper-redteam/.mcp.json