foolfuuka-mcp-server

MCP server for querying 4chan archives (Desuarchive, 4plebs, b4k, archived.moe) via the FoolFuuka API. Enables AI agents to search and retrieve historical archived posts through the Model Context Protocol.

Quick start

# Run directly (no install needed)
npx foolfuuka-mcp-server

# Or install globally
npm install -g foolfuuka-mcp-server
foolfuuka-mcp-server

Add to your MCP client config (Claude Desktop, VS Code, etc.):

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

Configuration

| Environment variable | Default | Description | |---|---|---| | FOOLFUUKA_BASE_URL | https://desuarchive.org | Root URL of a FoolFuuka archive | | FOOLFUUKA_USER_AGENT | foolfuuka-mcp-server/1.0 | User-Agent header sent with API requests | | FOOLFUUKA_BOARDS | none | Comma-separated board shortnames to display (e.g. "a,aco,an"). Overrides the default board list. When unset, desuarchive uses a curated subset matching its mirrors; other archives attempt the API then fall back to a full hardcoded list. |

[!TIP] Desuarchive works out of the box. For Cloudflare-protected archives (4plebs, archived.moe), you may need to run the server on a machine with the archive whitelisted, or use a different base URL.

Tools

search_archive

Full-text search across archived posts with filters.

Parameters: text, boards, subject, username, tripcode, capcode, filename, image, uid, country, deleted, ghost, filter, type, start, end, results, order, page

Returns a markdown table with Board, Thread, Post, Date, Author, Excerpt columns. OP posts are marked with (OP). Use single-board or multi-board mode depending on the boards parameter.

get_thread

Retrieve all posts in a thread.

Parameters: board, num, latest_doc_id (incremental), last_limit (default 100, pass 0 for all)

Returns the OP post and all replies in formatted markdown with author, timestamp, subject, content, and media attachments.

get_post

Retrieve a single post.

Parameters: board, num (supports _ suffix for ghost posts, e.g. "676_1")

Returns post details including author, date, board, thread number, subject, content, media (filename, dimensions, size), and image link when present.

list_boards

List available boards for the configured archive.

Parameters: none

Returns a markdown table of board shortnames and names, plus site name and search-enabled board count. The board list comes from FOOLFUUKA_BOARDS if set, otherwise a desuarchive-curated subset or API response depending on the archive. Boards not in the list still work for search and post lookups.

Examples

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_archive",
     "arguments": { "boards": "a", "text": "kamiina botan", "page": 1 }
  }
}

Response (single-board):

## Search: "kamiina botan" on /a/

Found 25 of 330 matching posts (page 1 of 200, 25 per page)

| Board | Thread | Post | Date | Author | Excerpt |
|-------|--------|------|------|--------|---------|
| /a/ | #288811815 | #288821283 | 2026-06-20 | Anonymous | They say in /au/ that Japanese otakus don't like Kamiina Botan... |
| /a/ | #288749749 | #288763277 | 2026-06-17 | Anonymous | So uh... How about that erm, K-Kamiina Botan? |
| /a/ | #288735782 | #288744910 | 2026-06-16 | Anonymous | Kamiina Botan is the best romance anime of the decade. |
| /a/ | #288692733 | #288705032 | 2026-06-14 | Anonymous | Kamiina Botan the best yuri anime adaptation of all time... |

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_thread",
    "arguments": { "board": "a", "num": 288342508 }
  }
}

Response:

## Thread #288342508 on /a/

**OP** by Anonymous — 2026-05-26 14:38:49 UTC
**Subject:** Marriagetoxin
> Best girl is here.
> 
> Sorry Kinosaki.
📎 [SubsPlease] MARRIAGETOXIN - 08 (720p) [50718D73].mkv-2026-05-26-10h38m13s978.jpg (1280×720, 234 KB)

---

**#288342579** by Anonymous — 2026-05-26 14:42:24 UTC
> why is Gero spending so much time with Mei on the weekend?
📎 [SubsPlease] MARRIAGETOXIN - 08 (720p) [50718D73].mkv-2026-05-26-10h42m06s075.jpg (1280×720, 244 KB)

---

**#288344069** by Anonymous — 2026-05-26 16:06:53 UTC
> Genuinely best girl.

---

**#288345985** by Anonymous — 2026-05-26 17:40:31 UTC
> >>288342508
> In a series of Best Girls, Hamster Lady is absolutely Best Best Girl.
> 
> Her main 'attack' is putting on a Carnivale costume and dancing with hamsters!

How it works

The server runs over stdio transport — it reads JSON-RPC messages from stdin and writes responses to stdout. There is no HTTP server.

LLM  <--MCP stdio-->  foolfuuka-mcp-server  <--HTTP-->  FoolFuuka Archive

All responses are formatted as markdown rather than raw JSON, making them natural for LLMs to consume without extra parsing.

Rate limits

FoolFuuka archives enforce rate limits (e.g., ~5 requests/minute on 4plebs). The server respects Retry-After headers on 429 responses and surfaces the wait time to the caller.

Development

git clone https://github.com/dynmie/foolfuuka-mcp-server.git
cd foolfuuka-mcp-server
npm install
npm run build
npm test

Tests are written with Vitest and live in tests/.

License

MIT