🎣 GoPhish MCP Server

A complete MCP (Model Context Protocol) server for interacting with all GoPhish API functionalities.

Features • Installation • Configuration • Usage • Tools

---

📝 Note: This MCP has been tested and works with GoPhish version 0.11.0. If I receive enough love 😊, I might update it with new capabilities!

---

✨ Key Features

🎯 Complete Campaign Management: Full CRUD + advanced analysis and statistics
👥 Group Management: Manage target user groups with search capabilities
📧 Email Templates: Create, edit and manage email templates
🌐 Landing Pages: Manage landing pages for campaigns
📮 SMTP Profiles: Configure email sending profiles
👤 User Management: Manage system users and administrators
📊 Analysis and Reports: Detailed statistics, data export and global analysis
🔍 Utility Tools: Search, validation, duplication and diagnostics

🚀 Quick Start

Installation

Clone this repository

git clone <repository-url>
cd gophish-mcp

Install dependencies:

pip install -e .

Configuration

Option 1: .env file (Recommended)

Copy the example file:

cp env.example .env

Edit .env with your credentials:

GOPHISH_URL=https://your-gophish-server:3333
GOPHISH_API_KEY=your-api-key-here

Option 2: Environment variables

export GOPHISH_URL="https://your-gophish-server:3333"
export GOPHISH_API_KEY="your-api-key"

💻 Usage with Claude, Cursor, VSCode, Kiro

Step 1: Configure Credentials (One time only)

Create a .env file in the project directory:

cp env.example .env
# Edit .env with your real credentials

Step 2: Configure MCP Client

Add the server to your MCP configuration (without credentials):

{
  "mcpServers": {
    "gophish": {
      "command": "python",
      "args": ["/path/to/your/gophish-mcp/server.py"],
      "cwd": "/path/to/your/gophish-mcp",
      "disabled": false,
      "autoApprove": [
        "gophish_get_campaigns",
        "gophish_get_campaign",
        "gophish_get_active_campaigns",
        "gophish_get_completed_campaigns",
        "gophish_get_recent_campaigns",
        "gophish_get_latest_campaign",
        "gophish_get_campaigns_summary",
        "gophish_get_campaign_results",
        "gophish_get_campaign_summary",
        "gophish_get_campaign_analytics",
        "gophish_get_global_analytics",
        "gophish_get_system_status",
        "gophish_search_campaigns",
        "gophish_search_groups",
        "gophish_search_templates",
        "gophish_get_groups",
        "gophish_get_templates",
        "gophish_get_pages",
        "gophish_get_smtp_profiles",
        "gophish_get_users",
        "gophish_get_campaign_by_status",
        "gophish_get_campaign_by_date_range",
        "gophish_get_campaign_targets",
        "gophish_get_campaign_events"
      ]
    }
  }
}

Step 3: Restart MCP Client

Restart your MCP client (Claude, Cursor, etc.)

🔒 Security Note: Credentials are only configured in the server's .env file, not in the client JSON. All tools listed in autoApprove are read-only according to the API implementation in server.py. Any create, update or delete operation (gophish_create_, gophish_update_, gophish_delete_*) will always require manual approval.

🛠️ Tool Categories

| Category | Description | |----------|-------------| | 📖 READ-ONLY | These tools only read data and are automatically approved by the MCP client | | ✏️ WRITE | These tools modify data and require manual approval for security |

📋 Available Tools

🎯 Campaigns (Complete Management)

Basic Operations

| Tool | Description | Type | |------|-------------|------| | gophish_get_campaigns | Get all campaigns | 📖 READ-ONLY | | gophish_get_campaign | Get details of a specific campaign | 📖 READ-ONLY | | gophish_create_campaign | Create new campaign | ✏️ WRITE | | gophish_update_campaign | Update existing campaign | ✏️ WRITE | | gophish_delete_campaign | Delete campaign | ✏️ WRITE |

Analysis and Statistics

| Tool | Description | Type | |------|-------------|------| | gophish_get_latest_campaign | Get latest campaign with complete statistics | 📖 READ-ONLY | | gophish_get_campaigns_summary | Get summary of last N campaigns | 📖 READ-ONLY | | gophish_get_campaign_results | Get detailed results of a campaign | 📖 READ-ONLY | | gophish_get_campaign_summary | Get summary with statistics of a campaign | 📖 READ-ONLY | | gophish_get_campaign_analytics | Get complete analysis of a campaign | 📖 READ-ONLY |

Filters and Search

| Tool | Description | Type | |------|-------------|------| | gophish_get_active_campaigns | Get active campaigns | 📖 READ-ONLY | | gophish_get_completed_campaigns | Get completed campaigns | 📖 READ-ONLY | | gophish_get_campaign_by_status | Filter campaigns by status | 📖 READ-ONLY | | gophish_get_recent_campaigns | Get campaigns from last N days | 📖 READ-ONLY | | gophish_get_campaign_by_date_range | Get campaigns in date range | 📖 READ-ONLY | | gophish_search_campaigns | Search campaigns by name | 📖 READ-ONLY |

Utilities

| Tool | Description | Type | |------|-------------|------| | gophish_get_campaign_targets | Get all targets of a campaign | 📖 READ-ONLY | | gophish_get_campaign_events | Get events of a campaign | 📖 READ-ONLY |

👥 Groups (Complete Management)

| Tool | Description | Type | |------|-------------|------| | gophish_get_groups | Get all groups | 📖 READ-ONLY | | gophish_create_group | Create new group | ✏️ WRITE | | gophish_update_group | Update existing group | ✏️ WRITE | | gophish_delete_group | Delete group | ✏️ WRITE | | gophish_search_groups | Search groups by name | 📖 READ-ONLY |

📧 Email Templates (Complete Management)

| Tool | Description | Type | |------|-------------|------| | gophish_get_templates | Get all templates | 📖 READ-ONLY | | gophish_create_template | Create new template | ✏️ WRITE | | gophish_update_template | Update existing template | ✏️ WRITE | | gophish_delete_template | Delete template | ✏️ WRITE | | gophish_search_templates | Search templates by name or subject | 📖 READ-ONLY |

🌐 Landing Pages (Complete Management)

| Tool | Description | Type | |------|-------------|------| | gophish_get_pages | Get all pages | 📖 READ-ONLY | | gophish_create_page | Create new page | ✏️ WRITE | | gophish_update_page | Update existing page | ✏️ WRITE | | gophish_delete_page | Delete page | ✏️ WRITE |

📮 SMTP Profiles (Complete Management)

| Tool | Description | Type | |------|-------------|------| | gophish_get_smtp_profiles | Get all SMTP profiles | 📖 READ-ONLY | | gophish_create_smtp_profile | Create new SMTP profile | ✏️ WRITE | | gophish_update_smtp_profile | Update existing SMTP profile | ✏️ WRITE | | gophish_delete_smtp_profile | Delete SMTP profile | ✏️ WRITE |

👤 User Management

| Tool | Description | Type | |------|-------------|------| | gophish_get_users | Get all users/administrators | 📖 READ-ONLY | | gophish_create_user | Create new user | ✏️ WRITE | | gophish_update_user | Update existing user | ✏️ WRITE |

📊 Global Analysis and Reports

| Tool | Description | Type | |------|-------------|------| | gophish_get_system_status | Get system status and general statistics | 📖 READ-ONLY | | gophish_get_global_analytics | Get global analysis of all campaigns | 📖 READ-ONLY |

💡 Usage Examples

Once configured, you can use commands like:

Basic Management

Show me all GoPhish campaigns

Create a new campaign called "Test Campaign" using template with ID 1

Update campaign with ID 5 to change its name to "Updated Campaign"

Analysis and Reports

Show me the complete analysis of campaign with ID 3

Get global statistics of all campaigns

Show me events from campaign 2

Search and Filters

Search campaigns containing "phishing" in the name

Show me all active campaigns

Get campaigns created in the last 7 days

User Management

List all system users

Create a new administrator user

Advanced Search

Search templates containing "urgent" in the subject

Find groups containing "marketing" in the name

🔒 Security

⚠️ Server disables SSL verification by default for local development
✅ Make sure to use HTTPS in production
🔑 Keep your API key secure and don't share it
🛡️ All write operations require valid authentication

🧪 Testing

Run Tests

# Run all tests
python test.py all

# Run read-only tests
python test.py readonly

# Run verbose demo
python test.py demo

# Run comprehensive tests
python test.py comprehensive

Testing Requirements

✅ GoPhish server running
✅ Valid credentials in .env
✅ Dependencies installed: pip install -e .

See tests/README.md for more details about testing.

🛠️ Utilities

Utility Scripts

# List campaigns
python utils/list_campaigns.py

🏗️ Development

For local development:

# Install in development mode
pip install -e .

# Run server directly
python server.py

# Run tests
python test.py all

📚 Additional Resources

Architecture Documentation - Learn about the server architecture
Test Results - View comprehensive test results

---

Made with ❤️ for the GoPhish community

⭐ Star this repo if you find it useful!

License

This project is licensed under the MIT License. See the LICENSE file for details.

gophish-mcp