tor

The Tor MCP Server provides a controlled gateway to browse onion services through the Tor network with built-in content filtering and safety guardrails. It exposes four main tools via MCP: tor_connect to test the Tor connection, tor_fetch to retrieve content from onion or regular sites through Tor, tor_status to verify that the Tor service is running, and tor_configure_filters to dynamically adjust filtering rules. Use these tools through your MCP client to establish a Tor-enabled browsing experience that contrasts your real IP with the Tor exit IP, fetch content safely, and tweak filters without restarting the server. The server enforces configurable keyword and domain blocks, redacts sensitive information from results, and supports timeouts to keep interactions responsive.

To get started, run the server, connect your MCP client, and begin issuing natural language commands like: "Test my Tor connection", "Fetch content from http://example.onion", or "Add 'suspicious-term' to blocked keywords". The available tools translate into structured JSON actions that your client can present to users and then relay to the server for execution.

Prerequisites

• Tor Browser or Tor service must be running (SOCKS proxy at 127.0.0.1:9150 for Tor Browser or 127.0.0.1:9050 for Tor service)
• Python 3.8+
• Access to install dependencies from requirements.txt

Setup steps

1. Clone the repository and navigate to the project directory:

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

2. Install Python dependencies:

pip install -r requirements.txt

3. Create or edit the configuration file as described in the documentation (tor_config.json in the project root).

4. Run the server:

python tor_mcp_server.py

Prerequisites recap:

• Ensure Tor is running and accessible via the configured SOCKS proxy.
• Use Python 3.8 or newer and install the dependencies listed in requirements.txt.

Configuration notes:

• The default configuration exposes socks_port, host, timeout_seconds, and connect_timeout_seconds under tor_settings. Adjust these to match your Tor setup and desired timeouts.
• Content filtering supports enabled, blocked_keywords (regex supported), warning_keywords, blocked_domains, blocked_url_patterns, allowed_domains, enable_content_redaction, and max_content_length. Tweak these to balance safety and accessibility.
• Use tor_configure_filters to dynamically adjust filters at runtime without restarting the server.

Common issues:

• If you see tor_connect indicating a failed connection, verify that the Tor proxy is running and that the SOCKS port and host in tor_config.json match your environment.
• Content blocks may appear if a keyword or domain is blacklisted; use tor_configure_filters to refine filters.
• For slow onion services, increase timeout settings in tor_settings.