🎣 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

Related MCP server: MailScript MCP Server

🚀 Quick Start

Installation

1. Clone this repository

git clone <repository-url>
cd gophish-mcp

2. Install dependencies:

pip install -e .

Configuration

Option 1: .env file (Recommended)

1. Copy the example file:

cp env.example .env

2. 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

📋 Available Tools

🎯 Campaigns (Complete Management)

Basic Operations

Analysis and Statistics

Filters and Search

Utilities

👥 Groups (Complete Management)

📧 Email Templates (Complete Management)

🌐 Landing Pages (Complete Management)

📮 SMTP Profiles (Complete Management)

👤 User Management

📊 Global Analysis and Reports

💡 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.