cheatforummcp

A TypeScript MCP server for reading and searching game-cheat forums — UnknownCheats (vBulletin) and CheatGlobal (XenForo). It uses Bun, a local Chrome window, and Cheerio to parse forum pages. Fork of amangly/mcp-unknowncheat extended with CheatGlobal support.

Local installation note: automatic Turnstile interaction is disabled in src/browser.ts; browser challenges and account sign-in are completed manually in the visible browser.

Demo

https://github.com/user-attachments/assets/9f00f783-0a03-4e8d-b5b6-abd308936f20

Related MCP server: Avito Personal MCP

Install

Install Bun and Google Chrome. The server uses puppeteer-real-browser and your installed browser; installation does not download a browser. Set UC_CHROME_PATH to an absolute Chrome or Chromium executable path if Chrome is not in its standard location. Clone and run the source:

git clone https://github.com/iiSwxft/cheatforummcp.git
cd cheatforummcp
bun install --frozen-lockfile
bun run start

The server uses MCP over standard input and output. Chrome opens when a tool first needs a page. It keeps a dedicated profile under the user's application data directory (mcp-unknowncheat/chrome-profile) so a manually completed browser challenge and login can survive restarts. Set UC_PROFILE_DIR to an absolute path to choose another profile; an existing cookies.json is imported only when the profile is first created. On Linux without a graphical display, Chrome runs headless; set UC_HEADLESS=1 to request headless mode elsewhere. If a Cloudflare challenge appears, complete it in the visible Chrome window. The server waits up to 45 seconds by default (UC_CF_WAIT_MS), subject to each tool's time budget. Automated browsers are not guaranteed to pass production challenges. Clients may need a tool timeout over 60 seconds for first-time manual setup.

Connect an MCP client

Install Bun and Chrome first. Your MCP client starts the server with bun run /absolute/path/to/cheatforummcp/src/index.ts; you do not need to leave a separate terminal running. The upstream UnknownCheats-only variant is also published as bunx mcp-unknowncheatz.

Codex

Add the server from a terminal (adjust the path to your checkout):

codex mcp add unknowncheat -- bun run C:/path/to/cheatforummcp/src/index.ts
codex mcp list

Or add this to ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml):

[mcp_servers.unknowncheat]
command = "bun"
args = ["run", "C:/path/to/cheatforummcp/src/index.ts"]
tool_timeout_sec = 120

Restart Codex after editing the config file.

Claude Code

claude mcp add --scope user unknowncheat -- bun run C:/path/to/cheatforummcp/src/index.ts
claude mcp list

Use --scope project if the server should be available only in one project.

Claude Desktop and Cursor

Add the server entry under mcpServers in the client's JSON config. Claude Desktop uses %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. Cursor uses ~/.cursor/mcp.json for all projects or .cursor/mcp.json in one project.

{
  "mcpServers": {
    "unknowncheat": {
      "command": "bun",
      "args": ["run", "C:/path/to/cheatforummcp/src/index.ts"]
    }
  }
}

Merge this entry into an existing mcpServers object if you already have other servers. Quit and reopen the client after saving the file.

VS Code

Add this to .vscode/mcp.json in your workspace, then run MCP: List Servers from the Command Palette to start or inspect it:

{
  "servers": {
    "unknowncheat": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "C:/path/to/cheatforummcp/src/index.ts"]
    }
  }
}

For other clients, configure a local stdio MCP server with command bun and args run + the absolute src/index.ts path. If the client cannot find bunx, use its absolute executable path. On first use, allow time for the package to start and for any browser challenge; where supported, set a tool timeout of at least 120 seconds. Ask the client to list its MCP tools or call check_login to confirm the connection.

Tools

CheatGlobal tools use the same shared Chrome session and Cloudflare handling as UnknownCheats. After a cleared page exists on an origin, same-origin requests run as in-page fetch() calls rather than full navigations, which avoids repeat challenges on aggressive configurations.

The MCP tool schemas provide the available arguments. For example:

search_forum({ query: "example" })
get_thread({ url: "https://www.unknowncheats.me/forum/showthread.php?t=123" })
find_latest_offsets({ game: "Apex Legends" })
index_subforum({ subforum: "apex-legends", max_listing_pages: 1, max_threads: 5 })
search_index({ query: "offsets", subforum: "apex-legends" })

The server advertises forum research tools for game cheating scenes, cheat techniques and tooling, anti-cheat, reversing, and offsets questions. The connected AI client decides whether to invoke them; tool descriptions and server instructions guide selection but do not force a call. For a current or newest claim, compare plausible threads and read their latest three pages before concluding. Search hits and the original post alone do not establish freshness. Check recentPagesComplete and the fetched page numbers; a timeout or page error means coverage is incomplete. If a recent post points to a code block, use extract_code on that page before citing values.

The first directory lookup saves forum URLs in forum-index.json. Offsets lookups read the selected game's live thread listing, then compare the latest three pages of up to three plausible threads. max_thread_pages and max_candidate_threads can extend the search. For games in a shared forum, they try indexed thread titles and then native forum search. Results include every scanned thread, its page coverage, errors, and separate flags for incomplete candidate scans and incomplete discovery. A matching post does not prove the offsets work with the current game build or that unscanned threads have no newer post. If the game name is ambiguous, use a slug returned by list_subforums or pass an exact thread_url.

Browsing or crawling a subforum records its visible listing in the local index. Reading a thread records the pages visited. index_subforum additionally samples the first and recent post pages of changed threads, up to five by default, and rechecks unchanged threads after 24 hours. The index remains partial: search_index includes listing and post page counts, timestamps, and a partial coverage marker. Use live search when freshness or missing coverage matters. The SQLite database is stored under the user's application data directory (mcp-unknowncheat/forum-index.sqlite); set UC_INDEX_PATH to change it. Browser-backed tools share one page and run one at a time; a queued call returns a busy error after 10 seconds. get_thread, bulk_get_threads, crawl_subforum, index_subforum, and find_latest_offsets stop starting new page requests after a 45-second fetch budget. crawl_cache reports cache hits, queued requests, failures, and total fetch time.

Development

If a tool returns connect ECONNREFUSED 127.0.0.1:<port> while Chrome stays on a blank page, update to a build containing the explicit debugging-port fix. chrome-launcher 1.2.2 can select an old port from the dedicated profile's accumulated log on restart. The server now allocates a fresh loopback port for each launch. Close any abandoned Chrome window using the dedicated MCP profile before restarting the server; keep your ordinary Chrome windows open. A profile must be used by only one server instance at a time. This startup error occurs before forum navigation and is separate from a Cloudflare verification loop.

bun run typecheck
bun run test
bun run build
bun run inspect:html -- path/to/saved-forum-page.html

The browser code and tools are in src/; HTML parsers are in src/parsers/. downloads/, exports/, cookies.json, and forum-index.json are local output ignored by Git. The HTML inspector reads a saved page locally and reports selector counts, parser coverage, pagination, and challenge markers without fetching the site.

Contributing

Read the contributing guide for setup and pull requests. The docs index links the architecture and testing guides. Bug reports should include the tool call, expected and actual result, and any page that could not be fetched; remove account data before posting.

Configuration

The upstream npm package is mcp-unknowncheatz (UnknownCheats only). Report bugs for this fork in GitHub Issues.

License

Apache License 2.0 from version 0.3.7. See LICENSE and NOTICE. Published versions through 0.3.6 remain MIT licensed.