UnknownCheats

An MCP (Model Context Protocol) server for programmatically interacting with the UnknownCheats forum. Bypasses Cloudflare protection using a real Chrome instance and provides structured data extraction via Cheerio.

npm version License: MIT

Features

• Cloudflare bypass — Uses puppeteer-real-browser with a headed Chrome instance to solve Turnstile challenges automatically
• Cookie persistence — Session cookies saved to cookies.json and reused across restarts
• Auto-recovery — Detects detached frame / browser crash errors and relaunches automatically
• 6 MCP tools — Login, search, thread reading, pagination, code extraction, and debug

Tools

Tool	Description	Parameters
check_login	Check if the browser session is logged in	—
login	Auto-fill credentials and log in	username, password
search_forum	Search UC or browse a subforum	query, subforum?
get_thread	Fetch thread posts with pagination	url, fetch_all_pages?
extract_code	Extract C++/C#/Python/Lua code blocks	url, limit?, export_to_file?
debug_page	Inspect raw page structure for debugging	url

extract_code details

Parameter	Default	Description
url	required	Thread URL
limit	10 (max 50)	Max blocks to return inline
export_to_file	false	Save all blocks to exports/<slug>_<timestamp>.json

When the limit is hit, the response includes truncated: true, last_post_id (so you know where to resume), and a hint on how many blocks were skipped. Each block also carries a postId so you can trace it back to the exact post on the page.

Stack

• Runtime: Bun
• Language: TypeScript (ESM)
• Protocol: @modelcontextprotocol/sdk
• Browser: puppeteer-real-browser
• Parsing: cheerio

Requirements

• Bun v1.0+
• Google Chrome / Chromium installed (required by puppeteer-real-browser)

Linux: Hyprland / Wayland / headless agents

On Linux, puppeteer-real-browser defaults to Xvfb. If Xvfb is not installed (common on Arch + Hyprland), Chrome may start without a visible window and Cloudflare Turnstile cannot be completed interactively.

This server detects a real session (DISPLAY or WAYLAND_DISPLAY) and then:

• sets disableXvfb: true so Chrome uses your compositor
• passes --ozone-platform=wayland when WAYLAND_DISPLAY or XDG_SESSION_TYPE=wayland is set

Optional environment variables:

Variable	Default	Purpose
UC_CF_WAIT_MS	15000	Max wait (ms) for Cloudflare challenge to clear after navigation

Manual login (first run):

export WAYLAND_DISPLAY=wayland-1   # Hyprland default socket under $XDG_RUNTIME_DIR
export XDG_RUNTIME_DIR=/run/user/$(id -u)
bun run scripts/manual-login.ts

Complete Cloudflare in the opened Chromium window, log in, then cookies.json is saved for MCP/Cursor.

Installation

# via npm
npx uc-mcp-server

# or clone
git clone https://github.com/amaralkaff/mcp-unknowncheat.git
cd mcp-unknowncheat
bun install

Setup with Claude Code

claude mcp add uc-mcp bun -- run "/path/to/mcp-unknowncheat/src/index.ts"

Or with npx:

claude mcp add uc-mcp npx -- uc-mcp-server

Setup with Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "uc-mcp": {
      "command": "npx",
      "args": ["uc-mcp-server"]
    }
  }
}

Usage

On first run, Chrome opens in headed mode. Log in manually or use the login tool:

login({ username: "your_username", password: "your_password" })

Cookies are saved automatically. Subsequent runs reuse the session.

Examples

# Check login status
check_login()

# Browse the Apex Legends subforum
search_forum({ subforum: "apex-legends" })

# Search across all forums
search_forum({ query: "pubg offsets" })

# Get a thread (single page)
get_thread({ url: "https://www.unknowncheats.me/forum/..." })

# Get all pages of a thread
get_thread({ url: "https://www.unknowncheats.me/forum/...", fetch_all_pages: true })

# Extract code blocks (up to 10 inline)
extract_code({ url: "https://www.unknowncheats.me/forum/..." })

# Extract all code blocks and save to file
extract_code({ url: "https://www.unknowncheats.me/forum/...", export_to_file: true })

Project Structure

src/
├── index.ts          # MCP server entry + tool registration
├── browser.ts        # Chrome lifecycle, Cloudflare bypass, cookie persistence
├── types.ts          # Shared TypeScript interfaces
├── tools/
│   ├── check-login.ts
│   ├── login.ts
│   ├── search-forum.ts
│   ├── get-thread.ts
│   ├── extract-code.ts
│   └── debug-page.ts
└── parsers/
    ├── thread.ts         # Post extraction, pagination
    ├── search-results.ts # Search result parsing
    ├── code-blocks.ts    # Code extraction + language detection
    └── tags.ts           # Thread tag detection ([Source], [Release], etc.)

Notes

• All logging uses console.error() — console.log() is reserved for the MCP stdio transport
• Thread pagination capped at 50 pages by default for fetch_all_pages
• Language detection supports: C++, C#, Python, Lua
• Exported files are saved to ./exports/ and are excluded from git and npm

Issues

Found a bug or want to request a feature? Open an issue at:

https://github.com/amaralkaff/mcp-unknowncheat/issues