# MCP Security Tools Server

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

![Status](https://img.shields.io/badge/status-active-success)
![Version](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Supported Tools](#supported-tools)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Usage](#usage)
- [API Integration](#api-integration)
- [Troubleshooting](#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:
```bash
# 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):
```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

```bash
# 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
```bash
# Run setup script
./setup.sh

# Or with Python
python3 setup.py
```

### 2. Configure API Keys
```bash
# 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
```bash
# 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)
```bash
# 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)

```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)

```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)

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

## 📖 Usage

### Using with Claude (via MCP)

```python
# 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
// 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

```bash
# 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

```json
{
  "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

```bash
# 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

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

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

# View logs
tail -f setup.log
```

### Performance Metrics

```bash
# 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"
```bash
# Ubuntu/Debian
sudo apt-get install nmap

# macOS
brew install nmap

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

#### 2. "API key invalid"
```bash
# Check .env file
cat .env | grep API_KEY

# Update with correct key
nano .env
```

#### 3. "Permission denied"
```bash
# Run with appropriate permissions
sudo python3 mcp_server.py

# Or fix file permissions
chmod +x mcp_server.py
```

#### 4. "Module not found"
```bash
# Activate virtual environment
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt
```

#### 5. "Port already in use"
```bash
# Change server port
export MCP_SERVER_PORT=8001

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

### Debug Mode

```bash
# 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

```bash
# 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](./SKILL.md) - AI integration guide
- [Requirements.txt](./requirements.txt) - Dependencies list
- [.env.example](./.env.example) - Configuration template

### Tool Documentation
- [Nmap Manual](https://nmap.org/book/man.html)
- [Cariddi GitHub](https://github.com/edoardottt/cariddi)
- [ParamSpider GitHub](https://github.com/devanshbatham/paramspider)
- [Metasploit Documentation](https://docs.rapid7.com/metasploit/)
- [Ngrok Docs](https://ngrok.com/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](#troubleshooting) section
2. Review [Documentation](#-additional-resources)
3. Check [GitHub Issues](https://github.com/antonlarimaraton/mcp-accses/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!** 🚀