Gophish MCP Server

基于 fastmcp 的 Gophish MCP 服务器，为大型语言模型提供完整的钓鱼活动管理功能。

📋 目录

• 概述
• 功能特性
• 快速开始
• 前置要求
• 环境变量配置
• 客户端配置
• 使用示例
• 故障排除
• 安全注意事项
• 最佳实践
• 项目结构
• 许可证

🎯 概述

这个 Gophish MCP 服务器可以与支持 MCP 协议的客户端集成，主要包括 Claude Desktop、Cursor 等。通过 MCP 协议，AI 可以智能地管理和操作 Gophish 钓鱼活动。

🌟 主要优势

• 完整的API覆盖：提供38个工具，涵盖Gophish的所有核心功能
• 智能集成：与Claude、Cursor等AI工具无缝集成
• 易于使用：简单的配置和直观的API调用
• 安全可靠：支持环境变量配置，避免硬编码敏感信息

🚀 功能特性

本MCP服务器提供38个工具，涵盖Gophish的所有核心功能：

📊 活动管理 (Campaign Management) - 7个工具

• 获取所有活动：get_campaigns()
• 创建活动：create_campaign(name, groups, template_name, page_name, smtp_name, url, launch_date, send_by_date)
• 获取活动统计：get_campaign_stats(campaign_id)
• 获取活动结果：get_campaign_results(campaign_id)
• 删除活动：delete_campaign(campaign_id)
• 完成活动：complete_campaign(campaign_id)
• 获取活动详情：get_campaign_by_id(campaign_id)

👥 用户组管理 (Group Management) - 8个工具

• 获取用户组：get_groups()
• 创建用户组：create_group(name, users)
• 更新用户组：update_group(group_id, name, users)
• 删除用户组：delete_group(group_id)
• 获取用户组详情：get_group_by_id(group_id)
• 获取用户组摘要：get_groups_summary()
• 获取单个用户组摘要：get_group_summary(group_id)
• 导入用户组：import_group(csv_file_path)

📧 邮件模板管理 (Template Management) - 6个工具

• 获取模板：get_templates()
• 创建模板：create_template(name, html, subject, text)
• 更新模板：update_template(template_id, name, html, subject, text)
• 删除模板：delete_template(template_id)
• 获取模板详情：get_template_by_id(template_id)
• 导入邮件模板：import_template(content, convert_links)

🌐 登录页面管理 (Page Management) - 6个工具

• 获取页面：get_pages()
• 创建页面：create_page(name, html, capture_credentials, capture_passwords, redirect_url)
• 更新页面：update_page(page_id, name, html, capture_credentials, capture_passwords, redirect_url)
• 删除页面：delete_page(page_id)
• 获取页面详情：get_page_by_id(page_id)
• 导入网站：import_site(url, include_resources)

📮 SMTP配置管理 (SMTP Management) - 5个工具

• 获取SMTP配置：get_smtp_profiles()
• 创建SMTP配置：create_smtp_profile(name, host, port, username, password, from_address, ignore_cert_errors)
• 更新SMTP配置：update_smtp_profile(smtp_id, name, host, port, username, password, from_address, ignore_cert_errors)
• 删除SMTP配置：delete_smtp_profile(smtp_id)
• 获取SMTP配置详情：get_smtp_profile_by_id(smtp_id)

👤 用户管理 (User Management) - 5个工具

• 获取用户：get_users()
• 创建用户：create_user(username, password, role)
• 更新用户：update_user(user_id, username, password, role)
• 删除用户：delete_user(user_id)
• 获取用户详情：get_user_by_id(user_id)

⚙️ 系统设置 (System Settings) - 1个工具

• 重置API密钥：reset_api_key()

🚀 快速开始

1. 克隆仓库

git clone https://github.com/OoO7ce/Gophish-mcp.git
cd Gophish-mcp

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

export GOPHISH_API_KEY="your_gophish_api_key_here"
export GOPHISH_HOST="https://localhost:3333"

4. 测试连接

python3 gophish_mcp_server.py

📋 前置要求

1. Python环境：确保已安装 Python 3.8+
2. 依赖安装：

   pip install -r requirements.txt
   

3. Gophish服务：需要有运行中的 Gophish 实例
4. 环境变量：设置必要的环境变量

🔧 环境变量配置

环境变量设置有两种不同的使用场景：

场景1：命令行直接运行MCP服务器

当您直接在命令行运行MCP服务器进行测试时，需要设置环境变量：

# Gophish API密钥（必需）
export GOPHISH_API_KEY="your_gophish_api_key_here"

# Gophish服务器地址（可选，默认为localhost:3333）
export GOPHISH_HOST="https://your-gophish-server.com:3333"

场景2：在MCP客户端配置中设置

在 Claude Desktop 等客户端的配置文件中，环境变量通过 env 字段设置（见下面的客户端配置部分）。

🔑 获取API密钥的方法：

1. 登录 Gophish 管理界面
2. 进入 Settings -> Account Settings
3. 复制 API Key

🖥️ 客户端配置

1. Claude Desktop 配置

在 Claude Desktop 中添加 MCP 服务器，需要修改配置文件：

macOS位置：~/Library/Application Support/Claude/claude_desktop_config.json Windows位置：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gophish": {
      "command": "python3",
      "args": ["/path/to/Gophish-mcp/gophish_mcp_server.py"],
      "env": {
        "GOPHISH_API_KEY": "your_gophish_api_key_here",
        "GOPHISH_HOST": "https://localhost:3333"
      }
    }
  }
}

2. Cursor 配置

在 Cursor 中，MCP 服务器通常通过扩展或配置文件添加：

{
  "mcpServers": {
    "gophish": {
      "command": "python3",
      "args": ["/path/to/Gophish-mcp/gophish_mcp_server.py"],
      "cwd": "/path/to/Gophish-mcp",
      "enabled": true,
      "env": {
        "GOPHISH_API_KEY": "your_gophish_api_key_here",
        "GOPHISH_HOST": "https://localhost:3333"
      }
    }
  }
}

3. 其他MCP客户端

对于其他支持 MCP 的客户端，基本配置格式类似：

{
  "servers": [
    {
      "name": "gophish",
      "command": ["python3", "/path/to/gophish_mcp_server.py"],
      "env": {
        "GOPHISH_API_KEY": "your_api_key",
        "GOPHISH_HOST": "https://localhost:3333"
      }
    }
  ]
}

🧪 测试连接

1. 命令行测试

直接运行 MCP 服务器测试连接（需要先设置环境变量）：

cd /path/to/Gophish-mcp
export GOPHISH_API_KEY="your_key"
export GOPHISH_HOST="https://localhost:3333"
python3 gophish_mcp_server.py

2. 客户端测试

在客户端中尝试调用简单的函数：

• 首先调用 get_campaigns() 验证连接
• 如果成功，说明 MCP 服务器配置正确

📝 使用示例

创建完整的钓鱼活动

1. 创建用户组:

   # 方法1：手动创建用户组
   create_group("技术部门", [
       {"first_name": "张三", "last_name": "李", "email": "zhangsan@company.com", "position": "系统管理员"},
       {"first_name": "王", "last_name": "五", "email": "wangwu@company.com", "position": "开发工程师"}
   ])
   
   # 方法2：从CSV文件导入用户组
   import_group("employees.csv")
   
   # 查看用户组摘要
   get_groups_summary()
   

2. 创建邮件模板:

   # 方法1：手动创建模板
   create_template(
       name="系统维护通知",
       html="<h2>系统维护通知</h2><p>亲爱的 {{.FirstName}}，请及时登录系统...</p>{{.Tracker}}",
       subject="重要：系统维护通知",
       text="亲爱的用户，请及时登录系统进行维护。"
   )
   
   # 方法2：从现有邮件导入模板
   import_template(
       content="原始邮件内容（RFC 2045格式）",
       convert_links=True  # 自动转换链接为 {{.URL}}
   )
   

3. 创建登录页面:

   # 方法1：手动创建页面
   create_page(
       name="Office365登录",
       html="<form><input type='email' name='email'><input type='password' name='password'></form>",
       capture_credentials=True,
       capture_passwords=False,  # 不捕获密码，避免明文存储
       redirect_url="https://office.com"
   )
   
   # 方法2：导入现有网站
   import_site(
       url="https://login.microsoftonline.com",
       include_resources=False
   )
   

4. 创建SMTP配置:

   create_smtp_profile(
       name="公司邮件服务器",
       host="smtp.company.com",
       port=587,
       username="noreply@company.com",
       password="password",
       from_address="noreply@company.com"
   )
   

5. 创建活动:

   # 方法1：立即启动活动
   create_campaign(
       name="员工安全意识测试",
       groups=["技术部门"],
       template_name="系统维护通知",
       page_name="Office365登录",
       smtp_name="公司邮件服务器",
       url="https://campaign.company.com/test123"
   )
   
   # 方法2：调度活动（在指定时间启动）
   create_campaign(
       name="员工安全意识测试",
       groups=["技术部门"],
       template_name="系统维护通知",
       page_name="Office365登录",
       smtp_name="公司邮件服务器",
       url="https://campaign.company.com/test123",
       launch_date="2024-01-15T09:00:00Z",  # 指定启动时间
       send_by_date="2024-01-15T17:00:00Z"  # 指定发送截止时间
   )
   

6. 监控活动:

   # 获取活动摘要统计
   get_campaign_stats(campaign_id)
   
   # 获取详细的活动结果和事件时间线
   get_campaign_results(campaign_id)
   
   # 完成活动
   complete_campaign(campaign_id)
   

🔧 故障排除

常见问题

1. 连接失败

   • 检查 Gophish 服务是否运行
   • 验证 API 密钥是否正确
   • 确认防火墙设置

2. 权限错误

   • 确保 Python 脚本有执行权限
   • 检查 API 密钥的权限范围

3. 环境变量问题

   • 确认环境变量正确设置
   • 在不同 shell 中可能需要重新设置

调试方法

1. 启用详细日志 在服务器代码中添加日志输出

2. 检查API响应 手动测试 Gophish API 端点

3. 验证MCP协议 使用 MCP 调试工具检查通信

🔒 安全注意事项

1. API密钥安全

   • 不要在代码中硬编码 API 密钥
   • 使用环境变量或安全的配置管理

2. 网络安全

   • 使用 HTTPS 连接 Gophish
   • 配置适当的防火墙规则

3. 权限控制

   • 为 MCP 服务器创建专用的 Gophish 用户
   • 限制 API 密钥的权限范围

💡 最佳实践

• 按部门或职能创建用户组
• 使用公司邮箱作为发件人地址
• 设置合适的重定向URL
• 定期更换API密钥
• 监控活动效果并及时调整

🔄 更新和维护

1. 定期更新依赖

   pip install --upgrade -r requirements.txt
   

2. 监控API变化 关注 Gophish API 的更新，及时调整服务器代码

3. 备份配置 定期备份 MCP 客户端配置和环境变量设置

📁 项目结构

Gophish-mcp/
├── gophish_mcp_server.py          # 核心MCP服务器代码
├── requirements.txt                # Python依赖配置
├── README.md                      # 使用说明文档
└── .gitignore                     # Git忽略文件配置

📄 许可证

本项目基于 MIT 许可证开源。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如果您遇到问题或有建议，请：

1. 查看 故障排除 部分
2. 提交 Issue
3. 联系维护者

⭐ 如果这个项目对您有帮助，请给我一个星标！