🛡️ Security Hunter MCP — Autonomous AI Security & Bug Hunting Server

🌟 Executive Summary

security-hunter-mcp is an advanced Model Context Protocol (MCP) server engineered specifically for authorized cybersecurity researchers, red teams, bug bounty hunters, and autonomous AI coding agents (Google Antigravity, Claude Desktop, Cursor, Windsurf, OpenAI Codex, GitHub Copilot, and Zed).

While traditional LLMs struggle with context-window amnesia, repeat redundant tests, risk leaking API keys, and fabricate non-verifiable exploit commands, Security Hunter MCP acts as an external cognitive cybersecurity co-processor:

🎯 The AI Agent tests and analyzes.
🧠 Security Hunter MCP remembers, deduplicates, sanitizes, organizes, and correlates everything.

Related MCP server: BugBounty MCP Server

🚀 Key Highlights & Superpowers

📸 Workflow Architecture

sequenceDiagram
    autonumber
    actor Hunter as Security Researcher / Hunter
    participant Agent as AI Agent (Antigravity / Claude / Cursor)
    participant MCP as Security Hunter MCP Server
    participant Redactor as Zero-Trust Secret Redactor
    participant DB as Async SQLAlchemy & SQLite FTS5

    Hunter->>Agent: "Begin security audit on api.target.com"
    Agent->>MCP: call create_project() & add_target()
    MCP->>DB: Store authorized scope and assets
    DB-->>MCP: Project ID & Target ID initialized
    Agent->>MCP: call get_endpoint_checklist(url, tech_stack)
    MCP-->>Agent: Dynamic tailored OWASP checklist returned
    Agent->>MCP: call start_test(category="INJECTION", subcategory="SQLi")
    Agent->>MCP: call save_request(headers, body)
    MCP->>Redactor: Scrub Bearer tokens, cookies, secrets
    Redactor-->>MCP: Sanitized payload
    MCP->>DB: Store immutable request record
    Agent->>MCP: call finish_test(result="CONFIRMED", confidence="HIGH")
    Agent->>MCP: call create_finding(...)
    MCP->>DB: Check duplicates via FTS5 & token similarity
    DB-->>MCP: Verified unique finding registered
    Agent->>MCP: call generate_poc() & generate_finding_report()
    MCP-->>Agent: Production-ready Markdown report with cURL PoC

📊 Head-to-Head Comparison Matrix

How does Security Hunter MCP stack up against other approaches?

⚡ Quick Start & Installation

Prerequisites

• Python: Version 3.11 or higher (Python 3.12, 3.13, 3.14 fully supported).

• Git: For cloning the repository.

• MCP Client: Google Antigravity IDE, Claude Desktop, Cursor, Windsurf, or any MCP client.

Step 1: Clone & Install

# Clone the repository
git clone https://github.com/vikrant-project/security-hunter-mcp.git
cd security-hunter-mcp

# Install in editable mode
pip install -e .

Step 2: Configure Environment

# Copy example configuration
cp .env.example .env

(Default settings use SQLite in ./data/security_hunter.db with automated secret scrubbing enabled. No external API keys required!)

Step 3: Initialize Database & Run Diagnostics

# Initialize SQLite database schema and FTS5 virtual tables
security-hunter init

# Run system health diagnostics
security-hunter doctor

Output:

Running Security Hunter diagnostics...
                            System Health Check                            
+-------------------------------------------------------------------------+
| Component            | Status | Details                                 |
|----------------------+--------+-----------------------------------------|
| Evidence Directory   | OK     | ./data/evidence                         |
| Exports Directory    | OK     | ./data/exports                          |
| Database Engine      | OK     | Connected                               |
| SQLite FTS5          | OK     | Virtual table active                    |
| Secret Redaction     | ACTIVE | Automatic bearer, cookie & secret scrub |
| Registered MCP Tools | OK     | 41 security tools loaded                |
+-------------------------------------------------------------------------+

🔌 Easy Step-by-Step Setup in Popular AI Agents

1. 🪐 Google Antigravity IDE Setup

Google Antigravity IDE supports both Global and Workspace-Scoped MCP servers.

Global Setup (Available in All Workspaces)

1. Open your Antigravity global MCP configuration file:

   • Windows: C:\Users\<username>\.gemini\config\mcp_config.json

   • macOS / Linux: ~/.gemini/config/mcp_config.json

2. Add the security-hunter server definition:

{
  "mcpServers": {
    "security-hunter": {
      "command": "security-hunter",
      "args": ["serve"],
      "env": {
        "DATABASE_URL": "sqlite+aiosqlite:///C:/project/ios/mcp-server/data/security_hunter.db",
        "LOG_LEVEL": "INFO",
        "REDACTION_ENABLED": "true"
      }
    }
  }
}

Workspace Setup (Scoped to Project Root)

Create a file at .agents/mcp_config.json inside your project root:

{
  "mcpServers": {
    "security-hunter": {
      "command": "security-hunter",
      "args": ["serve"]
    }
  }
}

2. 🤖 Anthropic Claude Desktop Setup

1. Open your Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json (C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json)

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add security-hunter under "mcpServers":

{
  "mcpServers": {
    "security-hunter": {
      "command": "security-hunter",
      "args": ["serve"]
    }
  }
}

3. Restart the Claude Desktop application.

3. 🖱️ Cursor IDE Setup

1. Open Cursor Settings (Ctrl + , or Cmd + ,).

2. Navigate to Features > MCP Servers.

3. Click + Add New MCP Server:

   • Name: security-hunter

   • Type: command

   • Command: security-hunter serve

4. Click Save. Look for the green active status indicator.

4. 💻 OpenAI Codex / GitHub Copilot / VS Code (Roo Code / Cline) Setup

For VS Code extensions like Roo Code or Cline:

1. Open the extension settings > MCP Servers.

2. Add the JSON block to your cline_mcp_settings.json:

{
  "mcpServers": {
    "security-hunter": {
      "command": "security-hunter",
      "args": ["serve"]
    }
  }
}

5. 🌊 Windsurf / Cascade (Codeium) Setup

1. Open Windsurf Settings or edit ~/.codeium/windsurf/mcp_config.json:

2. Add:

{
  "mcpServers": {
    "security-hunter": {
      "command": "security-hunter",
      "args": ["serve"]
    }
  }
}

6. ⚡ Zed IDE Setup

In your Zed settings file (~/.config/zed/settings.json):

{
  "context_servers": {
    "security-hunter": {
      "command": "security-hunter",
      "args": ["serve"]
    }
  }
}

🛠️ Complete MCP Tools Catalog (41 Tools)

Security Hunter MCP provides 41 production-ready tools categorized across 8 operational domains:

security-hunter-mcp
├── 1. Projects (5 tools)     ── [create, list, get, update, archive]
├── 2. Targets (4 tools)      ── [add, list, get, update]
├── 3. Endpoints (5 tools)    ── [add, get, list, update, search]
├── 4. Testing (7 tools)      ── [start, update, finish, get, history, status, checklist]
├── 5. Evidence (5 tools)     ── [save_req, save_resp, save_evd, get, list]
├── 6. Findings (6 tools)     ── [create, update, get, list, confirm, change_status]
├── 7. Intelligence (5 tools) ── [search_records, similar, duplicates, gaps, next_actions]
└── 8. Reporting (4 tools)    ── [generate_poc, generate_report, export, import]

1. Projects (5 Tools)

• create_project(name, description?, scope?, out_of_scope?, notes?, actor?): Register an authorized engagement with explicit scope boundaries.

• list_projects(status?, limit?): List security engagements with live vulnerability and endpoint counters.

• get_project(project_id): Retrieve project details by UUID or human ID (PROJ-000001).

• update_project(project_id, name?, description?, status?, scope?, out_of_scope?, notes?, actor?): Update project parameters.

• archive_project(project_id, actor?): Gracefully archive an engagement.

2. Targets (4 Tools)

• add_target(project_id, name, value, type, scope_status?, notes?, actor?): Add asset (Domain, IP, Subdomain, CIDR, URL, API).

• list_targets(project_id, scope_status?): Query registered assets with scope filters.

• get_target(target_id): Inspect asset details and discovery metadata.

• update_target(target_id, ...): Update target label, value, scope status, or notes.

3. Endpoints (5 Tools)

• add_endpoint(project_id, url, method?, target_id?, description?, authentication_required?, authentication_type?, technology?, actor?): Automatically calculates canonical pattern (/users/123 -> /users/{id}).

• get_endpoint(endpoint_id): Retrieve endpoint details, parameters, and testing history.

• list_endpoints(project_id, target_id?, method?, testing_status?, limit?): Filter discovered surface.

• update_endpoint(endpoint_id, method?, description?, testing_status?, technology?): Modify endpoint state.

• search_endpoints(project_id, query): Search by path pattern, method, or technology.

4. Testing & History (7 Tools)

• start_test(project_id, endpoint_id, category, subcategory?, hypothesis?, method?, agent_name?, ...): Record test execution.

• update_test(test_id, actual_behavior?, observation?, status?): Record interim test observations.

• finish_test(test_id, result, confidence, actual_behavior?, observation?, next_action?): Conclude test and calculate elapsed duration.

• get_test(test_id): Inspect specific test execution record.

• get_test_history(endpoint_id): Answers: "Have we already tested this endpoint?" Returns all categories, confidence, and open items.

• get_endpoint_testing_status(endpoint_id): Quick status check (NOT_TESTED, IN_PROGRESS, CONFIRMED).

• get_endpoint_checklist(endpoint_id): Returns dynamic OWASP security checklist tailored to endpoint technology.

5. Evidence & Traffic (5 Tools)

• save_request(url, method, test_id?, endpoint_id?, headers?, query_parameters?, body?): Stores request with mandatory secret scrubbing.

• save_response(status_code, request_id?, test_id?, headers?, body?, response_time_ms?): Stores sanitized response.

• save_evidence(project_id, title, type, content?, file_bytes_base64?, finding_id?, test_id?): Stores immutable evidence with SHA-256 digest.

• get_evidence(evidence_id): Retrieve evidence record and cryptographic hash.

• list_evidence(finding_id?, test_id?, limit?): Query stored artifacts and logs.

6. Findings & Vulnerabilities (6 Tools)

• create_finding(project_id, title, category, severity, status, what_is_it, why_is_it_a_bug, impact, reproduction_steps, remediation?, ...): Registers vulnerability with duplicate detection.

• get_finding(finding_id): Returns complete finding dossier and audit log.

• list_findings(project_id, status?, severity?, category?, limit?): Query findings filtered by status or CVSS severity.

• confirm_finding(finding_id, confirmed_by?): Transition finding to CONFIRMED with elapsed confirmation tracking.

• change_finding_status(finding_id, status, reason, actor?): Update lifecycle status with mandatory audit log reason.

• update_finding(finding_id, ...): Update finding title, impact, remediation, or description.

7. Intelligence & Gap Analysis (5 Tools)

• search_security_records(project_id, query): Full-text search across all tables using native SQLite FTS5.

• get_next_testing_actions(project_id): Answers: "What should I test next?" (Prioritizes MAYBE findings, incomplete tests, and untested endpoints).

• find_testing_gaps(project_id): Answers: "What have I missed?" (Identifies untested endpoints, missing categories, findings missing evidence).

• find_similar_findings(project_id, title, category?): Similarity scoring to prevent duplicate issue reports.

• find_duplicate_endpoints(project_id, url): Path clustering to prevent duplicate endpoint testing.

8. Reporting & Data Portability (4 Tools)

• generate_poc(finding_id): Generates real, evidence-backed cURL command from stored request/response.

• generate_finding_report(finding_id): Formats publication-ready Markdown bug report.

• export_project(project_id, format, output_path?): Export complete engagement to JSON archive or Markdown bundle.

• import_project(file_path, actor?): Restore project dataset from JSON archive.

📚 Contextual URI Resources & Built-in Prompts

10 Dynamic URI Resources

Security Hunter MCP exposes live contextual state directly via custom URIs:

• security://project/{project_id} — Engagement overview and metadata.

• security://project/{project_id}/scope — Scope boundaries and rules.

• security://project/{project_id}/targets — Active asset inventory.

• security://project/{project_id}/endpoints — Discovered attack surface.

• security://project/{project_id}/findings — Complete vulnerability registry.

• security://endpoint/{endpoint_id} — Detailed endpoint configuration.

• security://endpoint/{endpoint_id}/history — Full testing history and execution durations.

• security://endpoint/{endpoint_id}/checklist — Dynamic tailored security checklist.

• security://finding/{finding_id} — Finding details and audit trail.

• security://finding/{finding_id}/evidence — Attached immutable evidence items.

5 Reusable AI Prompts

Trigger automated workflows in your AI client with a single prompt:

• security_endpoint_review: Systematic non-redundant testing workflow.

• security_continue_testing: Resumes incomplete audits right where you left off.

• security_review_finding: Verification protocol before confirming vulnerabilities.

• generate_bug_report: Generates executive-ready bug bounty reports.

• analyze_testing_gaps: Comprehensive blind-spot audit.

💻 CLI Administration Reference

Security Hunter MCP includes a high-performance Typer CLI:

# Initialize database schema and FTS5 tables
security-hunter init

# Run system diagnostic health check
security-hunter doctor

# Apply Alembic schema migrations
security-hunter migrate

# Launch MCP server over standard input/output
security-hunter serve

# View engagement statistics dashboard
security-hunter stats

# Export engagement to portable JSON or Markdown
security-hunter export PROJ-000001 --format json --output engagement_backup.json

# Import engagement from backup archive
security-hunter import engagement_backup.json

🔐 Zero-Trust Security & Privacy Principles

1. 100% Local & Sovereign: No cloud dependency. All records reside on your local machine or private PostgreSQL instance.

2. Deterministic Redaction: Bearer tokens, JWT signatures, session cookies, passwords, and cloud API keys (AKIA..., AIza...) are stripped before writing to disk.

3. Cryptographic Verification: Evidence files and screenshots receive SHA-256 hashes immediately upon ingestion to guarantee chain-of-custody.

4. Non-Hallucinated Proofs-of-Concept: Reports are synthesized exclusively from verified HTTP traffic stored in the database. Missing fields explicitly display NOT PROVIDED.

🏷️ Comprehensive Keywords & Search Index (SEO Dominance)

Primary Search Topics

#mcp #model-context-protocol #mcp-server #fastmcp #ai-security #bug-bounty #penetration-testing #pentest #cybersecurity #ethical-hacking #red-team #vulnerability-scanner #appsec #infosec #security-tools #ai-agents #antigravity #claude-desktop #cursor-ide #windsurf #codex #copilot #zed-editor #owasp #owasp-top-10 #sqlite-fts5 #zero-trust #secret-redaction #poc-generator

250+ Categorized Search Index & Hashtags

Model Context Protocol (MCP) Ecosystem

#mcp #model-context-protocol #mcp-server #mcp-tools #mcp-resources #mcp-prompts #fastmcp #python-mcp-sdk #anthropic-mcp #claude-mcp #cursor-mcp #antigravity-mcp #windsurf-mcp #zed-mcp #copilot-mcp #roo-code-mcp #cline-mcp #continue-dev-mcp #ollama-mcp #local-ai-mcp #agentic-tools #mcp-client #mcp-protocol #stdio-mcp #sse-mcp #mcp-hub #mcp-directory #awesome-mcp #mcp-registry

AI Agents & Autonomous Workflows

#ai-agent #autonomous-agent #security-agent #penetration-testing-agent #bug-hunter-agent #ai-copilot #agentic-workflow #agent-memory #persistent-memory #long-term-memory #agent-state-management #ai-reasoning #hypothesis-testing #ai-assisted-security #agentic-security #autonomous-recon #ai-red-team #autonomous-pentest #ai-hacker #llm-security-tools #ai-auditor #multi-agent-system #agent-audit-log #subagent-orchestration

Penetration Testing & Ethical Hacking

#pentest #pentesting #penetration-testing #ethical-hacking #ethical-hacker #white-hat #red-team #red-teaming #offensive-security #offsec #security-audit #network-pentest #web-pentest #api-pentest #mobile-pentest #infrastructure-testing #security-assessment #vulnerability-assessment #vapt #black-box-testing #grey-box-testing #white-box-testing #threat-modeling #adversary-simulation

Bug Bounty Hunting Platforms & Methodologies

#bug-bounty #bug-hunter #bug-hunting #bounty-hunter #hackerone #bugcrowd #intigriti #yeswehack #synack #immunefi #web3-security #smart-contract-audit #bounty-tips #recon-tools #attack-surface #asm #scope-management #out-of-scope-prevention #poc-generation #curl-poc #exploit-poc #bug-report #reproduction-steps #triage-ready

Application Security (AppSec) & OWASP

#appsec #application-security #devsecops #owasp #owasp-top-10 #owasp-asvs #owasp-api-security #api-security #sqli #sql-injection #xss #cross-site-scripting #csrf #ssrf #server-side-request-forgery #idor #insecure-direct-object-reference #bola #broken-object-level-authorization #bfla #broken-function-level-authorization #jwt-vulnerabilities #oauth-security #cors-misconfiguration #rce #remote-code-execution #lfi #local-file-inclusion #rfi #remote-file-inclusion #xxe #xml-external-entity #rate-limiting #brute-force #session-fixation #business-logic-flaw #file-upload-vulnerabilities #prototype-pollution

Data Privacy, Secret Redaction & Zero Trust

#secret-redaction #credential-scrubbing #zero-trust #bearer-token-redaction #jwt-scrubbing #cookie-redaction #api-key-protection #data-sanitization #pii-protection #gdpr-compliance #local-first #offline-security #no-telemetry #privacy-preserving-ai #secure-by-design #sha256-evidence #immutable-audit-log #chain-of-custody

Software Architecture & Technologies

#python3 #python-security #fastmcp #pydantic-v2 #sqlalchemy2 #async-sqlalchemy #aiosqlite #sqlite-fts5 #full-text-search #bm25 #alembic-migrations #typer-cli #rich-terminal #rest-api #graphql-security #json-schema #markdown-reporting #curl #http-proxy #burp-suite-alternative #postman-alternative #security-memory-database

🤝 Contributing & Community

We welcome contributions from cybersecurity researchers, bug bounty hunters, and AI enthusiasts worldwide!

1. Fork the Repository: Click the Fork button at the top of this page.

2. Create a Feature Branch:

   git checkout -b feature/awesome-new-mcp-tool

3. Commit Your Changes:

   git commit -m "feat(mcp): add new reconnaissance tool"

4. Push to Your Branch:

   git push origin feature/awesome-new-mcp-tool

5. Open a Pull Request: Submit your PR with a description of the enhancement.

📄 License

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