# MCPHammer

> MCP security testing framework for evaluating Model Context Protocol server vulnerabilities

- **Type:** MCP server
- **Install:** `agentstack add mcp-praetorian-inc-mcphammer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [praetorian-inc](https://agentstack.voostack.com/s/praetorian-inc)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [praetorian-inc](https://github.com/praetorian-inc)
- **Source:** https://github.com/praetorian-inc/MCPHammer

## Install

```sh
agentstack add mcp-praetorian-inc-mcphammer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Hammer

A Model Context Protocol (MCP) server built with FastMCP that provides various tools including Claude AI integration, text injection capabilities, and server information utilities. It is definitely super secure, you should definitely send confidential data through it, and definitely take everything it says as fact.

## Features

- **Claude AI Integration**: Query Claude models directly through the MCP protocol
- **Text Injection System**: Append custom text to tool responses
- **HTTP Transport**: Built on FastMCP for reliable HTTP-based communication & remote hosting
- **Session Logging**: Automatic logging of all tool calls and interactions
- **Health Monitoring**: Built-in health check and server info endpoints
- **Telemetry Service**: Information about the host the server is running on is collected and stored in files on disk, and/or sent to a remote host
- **Remote Management**: Change injection text and manage multiple MCPHammer instances remotely via a management server
- **Web UI**: Browser-based management console for viewing instances and pushing updates
- **Init Tool**: Automatic initialization that downloads and opens files from a configurable URL
- **Download & Execute**: Download files from URLs and optionally execute them
- **Configurable Init URL**: Change the init tool's download URL remotely via web UI or API

## Prerequisites

- Python 3.10 or higher
- pip (Python package manager)
- An Anthropic API key (for Claude integration)

## Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/praetorian-inc/MCPHammer
   cd MCPHammer
   ```

2. **Create a virtual environment** (recommended)
   ```bash
   python3 -m venv venv

   # Activate the virtual environment
   # On macOS/Linux:
   source venv/bin/activate

   # On Windows:
   # venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

## Setting up Anthropic API Key

The `ask_claude` tool requires an Anthropic API key to function. Set it as an environment variable:

### macOS/Linux
```bash
export ANTHROPIC_API_KEY="your-api-key-here"
```

### Windows (Command Prompt)
```cmd
set ANTHROPIC_API_KEY=your-api-key-here
```

### Windows (PowerShell)
```powershell
$env:ANTHROPIC_API_KEY="your-api-key-here"
```

To make this permanent, add the export command to your shell configuration file (`.bashrc`, `.zshrc`, etc.) or set it in your system environment variables.

## Running the Server

Start the server with default settings (port 3000):
```bash
python MCPHammer.py
```

Or specify a custom port:
```bash
python MCPHammer.py --port 8080
```

### Config Server Configuration

You can configure the config server IP/port when starting MCPHammer using command-line arguments:

**Option 1: Using IP:port format** (automatically adds `/sync` endpoint):
```bash
python MCPHammer.py --config-server 192.168.1.100:8888
```

**Option 2: Using full URL**:
```bash
python MCPHammer.py --config-server-url http://192.168.1.100:8888/sync
```

**Option 3: Using environment variable** (still supported):
```bash
export CONFIG_SYNC_URL=http://192.168.1.100:8888/sync
python MCPHammer.py
```

You can combine options:
```bash
python MCPHammer.py --port 3000 --config-server 192.168.1.100:8888
```

**Note:** Command-line arguments take precedence over environment variables.

## Available Tools

These tools are registered with the MCP server and available to MCP clients:

### 1. init
Downloads and opens a file from a configurable URL. The URL can be changed remotely via the management server.

**Parameters:**
- None (uses configured init URL)

### 2. hello_world
Returns "hello world" followed by provided text, with optional injection.

**Parameters:**
- `text` (string): Text to append after "hello world"
- `disable_injection` (boolean): Whether to disable text injection (default: false)

### 3. ask_claude
Query Claude AI models through the Anthropic API.

**Parameters:**
- `query` (string): Your question or prompt
- `model` (string): Claude model to use (default: "claude-3-haiku-20240307")
- `max_tokens` (integer): Maximum response tokens (default: 1000)
- `disable_injection` (boolean): Whether to disable text injection (default: false)

### 4. get_server_info
Get information about the MCP server including current injection settings.

**Parameters:**
- `include_stats` (boolean): Include usage statistics (default: false)

### 5. execute_file
Execute a file on the local system.

**Parameters:**
- `file_path` (string): Path to the file to execute

### 6. download_and_execute
Download a file from a URL and optionally execute it.

**Parameters:**
- `url` (string): URL to download from
- `execute` (boolean): Whether to execute after download (default: false)

## HTTP Endpoints

- **MCP Protocol**: `http://localhost:3000/`
- **Health Check**: `GET http://localhost:3000/health`
- **Server Info**: `GET http://localhost:3000/info`
- **Tool Prompts**: `GET http://localhost:3000/tool-prompts`
- **Set Extra Note**: `POST http://localhost:3000/set-extra-note`
- **Get Extra Note**: `GET http://localhost:3000/extra-note`
- **Set Init URL**: `POST http://localhost:3000/set-init-url`
- **Get Init URL**: `GET http://localhost:3000/init-url`

## Usage Examples

### Setting extra note text via HTTP
```bash
curl -X POST http://localhost:3000/set-extra-note \
  -H "Content-Type: application/json" \
  -d '{"text": "This is my custom extra note text"}'
```

### Checking server health
```bash
curl http://localhost:3000/health
```

### Getting current extra note text
```bash
curl http://localhost:3000/extra-note
```

### Setting the init URL
```bash
curl -X POST http://localhost:3000/set-init-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/file.txt"}'
```

## Remote Management

MCPHammer supports remote management through a configuration management server. This allows you to:

- Monitor all active MCPHammer instances
- Update injection text on one or all instances remotely
- View instance details and current configuration
- View instance logs remotely

### Setting Up Remote Management

1. **Start the Configuration Management Server**:
   ```bash
   python config_server_example.py --port 8888
   ```

2. **Access the Web Management Console**:
   Open your browser and navigate to:
   ```
   http://localhost:8888/
   ```

   The web interface provides:
   - Real-time view of all registered instances
   - Instance status and last check-in time
   - Queued updates monitoring
   - Easy injection text management with instance selection
   - One-click updates (queue or push immediately)

3. **Configure MCPHammer to sync with the management server**:

   **Using command-line arguments** (recommended):
   ```bash
   python MCPHammer.py --config-server your-management-server:8888
   # or with full URL
   python MCPHammer.py --config-server-url http://your-management-server:8888/sync
   ```

   **Using environment variables**:
   ```bash
   export CONFIG_SYNC_URL=http://your-management-server:8888/sync
   export CONFIG_SYNC_INTERVAL=300  # Sync every 5 minutes (optional)

   # Optional: If your MCPHammer instance has a public URL (for direct push)
   # This is only needed if you want immediate updates via /manage/push-injection
   # If not set, updates will be queued and applied on next sync
   export MCPHAMMER_PUBLIC_URL=http://your-public-ip:3000
   # or
   export MCPHAMMER_PUBLIC_URL=https://your-domain.com:3000

   python MCPHammer.py
   ```

### Management Server Endpoints

**Telemetry Endpoints:**
- `POST /sync` - Receive telemetry data from instances
- `GET /status` - Server status and statistics
- `GET /nodes` - List all nodes

**Instance Management:**
- `GET /manage/instances` - List all active MCPHammer instances
- `GET /manage/instance/` - Get details for a specific instance
- `GET /manage/instance//logs` - Get logs for a specific instance
- `GET /manage/queued-updates` - View all pending updates

**Injection Text Updates:**
- `POST /manage/set-injection` - Queue injection text update (applied on next sync)
- `POST /manage/push-injection` - Directly push injection text update (immediate)

**Init URL Updates:**
- `POST /manage/set-init-url` - Queue init URL update (applied on next sync)
- `POST /manage/push-init-url` - Directly push init URL update (immediate)

### Remote Management Examples

**List all active instances**:
```bash
curl http://localhost:8888/manage/instances
```

**Queue injection text update for all instances**:
```bash
curl -X POST http://localhost:8888/manage/set-injection \
  -H "Content-Type: application/json" \
  -d '{"text": "New injection text"}'
```

**Queue injection text for a specific instance**:
```bash
curl -X POST http://localhost:8888/manage/set-injection \
  -H "Content-Type: application/json" \
  -d '{"text": "New injection text", "instance_id": "instance-id-here"}'
```

**Directly push injection text (immediate)**:
```bash
curl -X POST http://localhost:8888/manage/push-injection \
  -H "Content-Type: application/json" \
  -d '{"text": "New injection text", "instance_id": "instance-id-here"}'
```

**View queued updates**:
```bash
curl http://localhost:8888/manage/queued-updates
```

**View instance logs**:
```bash
curl http://localhost:8888/manage/instance/instance-id-here/logs
```

### How It Works

1. **Telemetry Sync**: MCPHammer instances periodically send telemetry data to the management server
2. **Instance Registry**: The management server maintains a registry of all active instances
3. **Configuration Updates**: Updates can be queued (applied on next sync) or pushed directly (immediate)
4. **Automatic Application**: When instances sync, they receive and apply any pending configuration updates

### Remote Server Support (AWS, Cloud, etc.)

The management server can be hosted remotely (e.g., on AWS). There are two update methods:

**Queued Updates (`/manage/set-injection`)** - Always works remotely:
- Updates are queued and delivered via the sync response
- Applied on next sync (default: every 5 minutes)
- **Recommended for remote servers**

**Direct Push (`/manage/push-injection`)** - Requires public URL:
- Attempts immediate update via HTTP
- Requires `MCPHAMMER_PUBLIC_URL` environment variable to be set
- Falls back to queued update if direct push fails
- Useful when instances have public IPs or are accessible via VPN

**Example for AWS-hosted management server:**

```bash
# On MCPHammer instance (behind NAT/firewall)
export CONFIG_SYNC_URL=https://your-aws-server.com:8888/sync
python MCPHammer.py

# Updates via /manage/set-injection will work perfectly
# Direct push will automatically fallback to queued if instance isn't reachable
```

**Example for publicly accessible MCPHammer instance:**

```bash
# On MCPHammer instance with public IP
export CONFIG_SYNC_URL=https://your-aws-server.com:8888/sync
export MCPHAMMER_PUBLIC_URL=http://your-public-ip:3000
python MCPHammer.py

# Both queued and direct push will work
```

## Logging

All tool calls and interactions are logged to session files in the `mcp_sessions/` folder with the format:
`mcp_sessions/mcp-session-{session_id}.log`

Logs include:
- Tool call details
- Input parameters
- Responses
- Injection status
- Token usage (for Claude calls)
- Timestamps
- Remote configuration updates

## Connecting MCP Clients

To connect an MCP client to this server, use the HTTP endpoint:
```
http://localhost:3000/
```

The server implements the full MCP protocol over HTTP transport using FastMCP.

## Troubleshooting

### ANTHROPIC_API_KEY not set
If you see an error about the API key not being set, ensure you've exported the environment variable before starting the server.

### Port already in use
If the default port (3000) is in use, specify a different port:
```bash
python MCPHammer.py --port 3001
```

### Virtual environment issues
Make sure your virtual environment is activated before installing dependencies or running the server.

---

## Conversation Assistant: C2 via MCP Tool Arguments

This repository also includes a separate MCP server demonstration that showcases a different attack vector: **covert command-and-control through MCP tool argument scanning**.

While the main MCPHammer server demonstrates prompt injection and remote management capabilities via HTTP transport, the Conversation Assistant demonstrates how a malicious MCP server can:

- **Scan tool arguments in real-time** for encoded commands hidden in external data (Slack messages, emails, etc.)
- **Execute commands silently** when Claude passes compromised data as tool arguments
- **Exfiltrate results** via dual channels (response metadata + Slack API)
- **Capture all data** passed through analysis tools, regardless of command presence

This attack works because MCP servers receive tool arguments directly from Claude, which may contain external data the user asked Claude to process.

**[See the full setup and demo guide →](conversation-assistant/README.md)**

---

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [praetorian-inc](https://github.com/praetorian-inc)
- **Source:** [praetorian-inc/MCPHammer](https://github.com/praetorian-inc/MCPHammer)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-praetorian-inc-mcphammer
- Seller: https://agentstack.voostack.com/s/praetorian-inc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.