Tor MCP Server

A Model Context Protocol (MCP) server that provides secure access to Tor/onion services with built-in content filtering and safety guardrails. This server allows AI assistants like Claude to safely browse .onion sites and access content through the Tor network while maintaining strong safety protections.

🌟 Features

• Tor Network Access: Connect to .onion services and browse through Tor anonymously

• Content Filtering: Configurable keyword and domain filtering with safety guardrails

• Safety First: Built-in protections against harmful content with customizable filters

• JSON Configuration: Easy-to-manage configuration file for all settings

• Connection Testing: Built-in tools to verify Tor connectivity and service status

• Content Redaction: Automatic filtering of sensitive information (emails, SSNs, etc.)

• Flexible Timeouts: Configurable connection and request timeouts

• Real-time Filter Management: Dynamic filter configuration without restart

🛠️ Installation

Prerequisites

1. Tor Browser or Tor Service must be running on your system

   • Download from: https://www.torproject.org/download/

   • Default SOCKS proxy runs on 127.0.0.1:9150 (Tor Browser) or 127.0.0.1:9050 (Tor service)

2. Python 3.8+ is required

Setup

1. Clone this repository:

git clone <your-repo-url>
cd tor-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Create your configuration file (see Configuration section below)

4. Run the server:

python tor_mcp_server.py

⚙️ Configuration

Create a tor_config.json file in the same directory as the server script. Here's the default configuration:

{
  "tor_settings": {
    "socks_port": 9150,
    "host": "127.0.0.1", 
    "timeout_seconds": 60,
    "connect_timeout_seconds": 30
  },
  "content_filtering": {
    "enabled": true,
    "blocked_keywords": [
      "\\bchild abuse\\b",
      "\\bdrug dealer\\b", 
      "\\bhuman trafficking\\b"
    ],
    "warning_keywords": [
      "ransomware",
      "malware", 
      "stolen data"
    ],
    "blocked_domains": [],
    "blocked_url_patterns": [
      ".*porn.*",
      ".*adult.*"
    ],
    "allowed_domains": [],
    "enable_content_redaction": true,
    "max_content_length": 100000
  },
  "server_settings": {
    "server_name": "tor-access",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; rv:91.0) Gecko/20100101 Firefox/91.0",
    "max_redirects": 5
  }
}

Configuration Options

Tor Settings

• socks_port: Port for Tor SOCKS proxy (9150 for Tor Browser, 9050 for Tor service)

• host: Host address for Tor proxy (usually 127.0.0.1)

• timeout_seconds: Total request timeout

• connect_timeout_seconds: Connection establishment timeout

Content Filtering

• enabled: Enable/disable content filtering

• blocked_keywords: Keywords that will block content entirely (supports regex)

• warning_keywords: Keywords that will show warnings but allow content

• blocked_domains: Domain names to block completely

• blocked_url_patterns: URL patterns to block (regex supported)

• allowed_domains: Whitelist of allowed domains (empty = allow all except blocked)

• enable_content_redaction: Automatically redact sensitive info (emails, SSNs, etc.)

• max_content_length: Maximum content length to display

🔧 Available Tools

The server provides four main tools:

1. tor_connect

Test your Tor connection and verify it's working properly.

Usage:

{
  "tool": "tor_connect",
  "arguments": {}
}

Returns: Connection status, your real IP vs Tor exit IP

2. tor_fetch

Fetch content from onion services or regular websites through Tor.

Usage:

{
  "tool": "tor_fetch", 
  "arguments": {
    "url": "http://example.onion",
    "timeout": 30
  }
}

Parameters:

• url (required): The onion service URL or regular URL to fetch

• timeout (optional): Request timeout in seconds (default: 30)

3. tor_status

Check if Tor service is running and accessible.

Usage:

{
  "tool": "tor_status",
  "arguments": {}
}

4. tor_configure_filters

Dynamically configure content filtering settings.

Usage:

{
  "tool": "tor_configure_filters",
  "arguments": {
    "action": "add_blocked_keyword",
    "value": "malicious_term"
  }
}

Actions:

• add_blocked_keyword / remove_blocked_keyword

• add_warning_keyword / remove_warning_keyword

• add_blocked_domain / remove_blocked_domain

• list_filters: Show current filter configuration

• reload_config: Reload configuration from file

🛡️ Safety Features

Content Filtering

• Keyword Filtering: Block or warn on configurable keywords (with regex support)

• Domain Blocking: Block entire domains or URL patterns

• Content Analysis: Heuristic detection of ransomware sites and illegal marketplaces

• Content Redaction: Automatic removal of emails, SSNs, credit cards from displayed content

Built-in Protections

• Blocks harmful content categories by default

• Warns on potentially dangerous content

• Rate limiting and content size limits

• Safe defaults with ability to customize

Responsible Use

This tool is designed for:

• ✅ Security research and education

• ✅ Privacy-focused browsing

• ✅ Accessing legitimate onion services

• ✅ Investigating threats for cybersecurity purposes

Not intended for:

• ❌ Accessing illegal content

• ❌ Bypassing legitimate restrictions

• ❌ Any harmful or illegal activities

🚀 Usage with Claude/MCP

1. Start the Tor MCP Server

2. Configure your MCP client to connect to the server

3. Use natural language commands:

   • "Test my Tor connection"

   • "Fetch content from [onion-url]"

   • "Check if Tor is running"

   • "Add 'suspicious-term' to blocked keywords"

📋 Requirements

• Python 3.8+

• Tor Browser or Tor service running

• Dependencies from requirements.txt:

  • mcp>=1.0.0

  • aiohttp>=3.8.0

  • aiohttp-socks>=0.8.0

  • pydantic>=2.0.0

  • openai>=1.0.0

🔍 Troubleshooting

Common Issues

"Tor connection failed"

• Ensure Tor Browser is running or Tor service is started

• Check if the SOCKS port (9150/9050) is correct

• Verify host/port settings in config

"Content blocked"

• Content triggered safety filters

• Review and adjust blocked_keywords or blocked_domains in config

• Use tor_configure_filters to modify filters

"Request timed out"

• Increase timeout values in config

• Onion services can be slow - try longer timeouts

• Check if the onion service is online

Debug Mode

Run with verbose logging:

PYTHONPATH=. python tor_mcp_server.py --verbose

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new features

4. Submit a pull request

⚠️ Disclaimer

This tool is for legitimate security research and privacy purposes only. The authors are not responsible for misuse. Always comply with applicable laws and use responsibly.

Need help? Open an issue on GitHub or check the troubleshooting section above.