MCP Security Tools Server

A comprehensive Model Context Protocol (MCP) server integrating multiple security and reconnaissance tools for AI systems (Claude, Grok, etc.).

📋 Table of Contents

• Overview
• Features
• Supported Tools
• Requirements
• Installation
• Quick Start
• Configuration
• Usage
• API Integration
• Troubleshooting

🎯 Overview

This MCP Server provides AI systems with access to enterprise-grade security testing tools. It enables:

• Automated Reconnaissance: Network scanning, API discovery, parameter enumeration
• API Security Testing: Endpoint discovery, parameter testing, vulnerability detection
• Web Application Security: JavaScript rendering, dynamic content extraction
• Exploitation & Testing: Metasploit framework integration for advanced testing
• Remote Access: Ngrok tunnel support for cloud-based AI systems

✨ Features

✅ Automated Setup - One-command installation with dependency checking
✅ Virtual Environment - Isolated Python environment for security
✅ Multiple Tools - 6 specialized security tools integrated
✅ API Key Management - Secure handling of authentication tokens
✅ Ngrok Integration - Remote access via secure tunnels
✅ AI-Ready - MCP protocol support for Claude, Grok, and other AI systems
✅ Comprehensive Logging - Detailed operation logs for debugging
✅ Error Handling - Graceful error management and recovery
✅ Skill Documentation - AI-friendly documentation (SKILL.md)
✅ Cross-Platform - Linux, macOS, and Windows support

🛠️ Supported Tools

1. Nmap - Network Reconnaissance

• Port scanning
• Service detection
• OS fingerprinting
• Network mapping

2. Cariddi - API Endpoint Discovery

• Sensitive endpoint detection
• Secret pattern matching
• API documentation analysis
• Vulnerability scanning

3. ParamSpider - Parameter Discovery

• Historical parameter extraction
• Hidden parameter discovery
• Injection point identification
• Endpoint parameter mapping

4. Metasploit Framework - Exploitation

• Vulnerability exploitation
• Payload generation
• Post-exploitation activities
• Social engineering

5. Web Scraper (ScrapingAnt) - Content Extraction

• JavaScript rendering
• Dynamic content extraction
• Proxy rotation
• Anti-detection features

6. MSFConsole - Advanced Penetration Testing

• Interactive exploitation
• Custom module development
• Automation scripting
• Multi-stage exploitation

📦 Requirements

System Requirements

• OS: Linux (Ubuntu 20.04+), macOS 10.14+, or Windows 10+
• Python: 3.8 or higher
• Memory: 2GB minimum (4GB recommended)
• Disk Space: 2GB for tools and dependencies
• Internet: Required for downloading tools and API access

Required Tools (System Level)

• Git - Version control
• Nmap - Network scanning
• Python 3.8+ - Programming language

Optional Tools

• Metasploit Framework - Advanced exploitation
• Docker - Containerized deployment

🚀 Installation

Option 1: Automated Setup (Recommended)

Linux/macOS:

# Clone repository
git clone https://github.com/antonlarimaraton/mcp-accses.git
cd mcp-accses

# Make setup script executable
chmod +x setup.sh

# Run setup
./setup.sh

Windows (PowerShell):

# Clone repository
git clone https://github.com/antonlarimaraton/mcp-accses.git
cd mcp-accses

# Run Python setup
python3 setup.py

Option 2: Manual Setup

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install system tools
# Ubuntu/Debian:
sudo apt-get install nmap metasploit-framework

# macOS:
brew install nmap
brew install metasploit

⚡ Quick Start

1. Initial Setup

# Run setup script
./setup.sh

# Or with Python
python3 setup.py

2. Configure API Keys

# Copy example environment file
cp .env.example .env

# Edit with your API keys
nano .env

Required API keys:

• ScrapingAnt: https://www.scrapingant.com/
• Ngrok: https://dashboard.ngrok.com/

3. Start MCP Server

# Activate virtual environment
source venv/bin/activate

# Run server
python3 mcp_server.py

# Check server status
curl http://localhost:8000/status

4. Enable Ngrok Tunnel (Optional)

# Start with remote access
python3 mcp_server.py --ngrok

# Get public URL from ngrok
# Share with AI systems for remote access

⚙️ Configuration

Environment Variables (.env)

# API Keys
SCRAPINGANT_API_KEY=your_key_here
NGROK_AUTHTOKEN=your_token_here

# Server Settings
MCP_SERVER_PORT=8000
MCP_SERVER_HOST=0.0.0.0
DEBUG_MODE=false

# Tool Configuration
ENABLE_NMAP=true
ENABLE_CARIDDI=true
ENABLE_PARAMSPIDER=true
ENABLE_METASPLOIT=true
ENABLE_WEB_SCRAPER=true

MCP Configuration (mcp_config.json)

{
  "name": "Security Tools MCP Server",
  "version": "1.0.0",
  "tools": {
    "nmap": {"enabled": true},
    "cariddi": {"enabled": true},
    "paramspider": {"enabled": true},
    "metasploit": {"enabled": true},
    "web_scraper": {"enabled": true}
  }
}

Ngrok Configuration (ngrok_config.json)

{
  "authtoken": "your_ngrok_token",
  "region": "ap",
  "log_level": "info"
}

📖 Usage

Using with Claude (via MCP)

# Example: Scan for vulnerabilities
curl -X POST http://localhost:8000/tools/nmap \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.1", "args": "-sV"}'

Using with Grok or Other AI Systems

// JavaScript example
const response = await fetch('http://localhost:8000/tools/cariddi', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_api_key'
  },
  body: JSON.stringify({
    url: 'https://target.com'
  })
});

Direct Tool Usage

# Activate environment
source venv/bin/activate

# Nmap
nmap -sV target.com

# Cariddi
cariddi -u https://target.com

# ParamSpider
python3 tools/paramspider/paramspider.py -d target.com

# Web Scraper
python3 -c "from mcp_server import MCPServer; \
server = MCPServer(); \
result = server.scrape_with_api('https://target.com')"

🌐 API Integration

Endpoints

GET  /status
GET  /health
POST /tools/nmap
POST /tools/cariddi
POST /tools/paramspider
POST /tools/metasploit
POST /tools/scrape
GET  /config

Response Format

{
  "status": "success",
  "tool": "nmap",
  "timestamp": "2026-01-01T12:00:00Z",
  "data": {
    "results": [...],
    "count": 42
  },
  "error": null
}

🔒 Security Considerations

⚠️ Important Security Notes:

1. Authorization Only - Use only on targets you own or have written permission to test
2. Legal Compliance - Ensure compliance with local laws and regulations
3. API Keys - Never commit API keys to version control
4. Rate Limiting - Implement rate limiting to avoid service disruption
5. Logging - Enable comprehensive logging for audit trails
6. Network - Use VPN for remote operations
7. Credentials - Rotate API keys regularly

Best Practices

# Use .env for sensitive data
export $(cat .env | xargs)

# Enable debug logging
export DEBUG_MODE=true

# Run in isolated environment
source venv/bin/activate

# Monitor tool execution
tail -f setup.log

📊 Monitoring

Check Server Status

# Health check
curl http://localhost:8000/health

# Tool status
curl http://localhost:8000/status

# View logs
tail -f setup.log

Performance Metrics

# Monitor resource usage
watch -n 1 'ps aux | grep mcp_server'

# Check port usage
netstat -tulpn | grep 8000

🐛 Troubleshooting

Common Issues

1. "nmap not found"

# Ubuntu/Debian
sudo apt-get install nmap

# macOS
brew install nmap

# Windows
# Download from https://nmap.org/download.html

2. "API key invalid"

# Check .env file
cat .env | grep API_KEY

# Update with correct key
nano .env

3. "Permission denied"

# Run with appropriate permissions
sudo python3 mcp_server.py

# Or fix file permissions
chmod +x mcp_server.py

4. "Module not found"

# Activate virtual environment
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

5. "Port already in use"

# Change server port
export MCP_SERVER_PORT=8001

# Or kill process on port 8000
lsof -ti:8000 | xargs kill -9

Debug Mode

# Enable debug logging
export MCP_DEBUG=1
export DEBUG_MODE=true
export LOG_LEVEL=DEBUG

# Run server with debug
python3 mcp_server.py --debug

# View detailed logs
tail -n 100 setup.log | grep ERROR

Log Files

# Check setup log
cat setup.log

# Watch real-time logs
tail -f setup.log

# Search for errors
grep ERROR setup.log

# Count occurrences
grep -c ERROR setup.log

📚 Additional Resources

Documentation

• SKILL.md - AI integration guide
• Requirements.txt - Dependencies list
• .env.example - Configuration template

Tool Documentation

• Nmap Manual
• Cariddi GitHub
• ParamSpider GitHub
• Metasploit Documentation
• Ngrok Docs

External Links

• GitHub: https://github.com/antonlarimaraton/mcp-accses
• Issues: https://github.com/antonlarimaraton/mcp-accses/issues

🤝 Contributing

Contributions welcome! Please:

1. Fork repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Create Pull Request

📝 License

MIT License - See LICENSE file for details

⚖️ Legal Notice

This tool is provided for authorized security testing only. Unauthorized access to computer systems is illegal. Users are responsible for compliance with all applicable laws and regulations.

🆘 Support

For issues and questions:

1. Check Troubleshooting section
2. Review Documentation
3. Check GitHub Issues
4. Contact maintainers

📋 Checklist for First-Time Use

• [ ] Clone repository
• [ ] Run setup script
• [ ] Configure API keys (.env)
• [ ] Install system tools
• [ ] Test individual tools
• [ ] Start MCP server
• [ ] Verify connectivity
• [ ] Setup Ngrok (optional)
• [ ] Test with AI system
• [ ] Review logs

🗺️ Project Status

Component	Status	Notes
Setup Script	✅ Ready	Automated installation
Nmap Integration	✅ Ready	Full support
Cariddi Integration	✅ Ready	API discovery
ParamSpider Integration	✅ Ready	Parameter enumeration
Metasploit Integration	✅ Ready	Exploitation framework
Web Scraper	✅ Ready	JavaScript rendering
Ngrok Support	✅ Ready	Remote access
MCP Protocol	✅ Ready	AI integration
Documentation	✅ Complete	SKILL.md included

---

Last Updated: 2026-01-01
Version: 1.0.0
Maintainer: Security Tools Team

Ready to start? Run ./setup.sh or python3 setup.py now! 🚀