One Piece Wiki MCP Server

@wlahsib/mcp-onepiece on npm

An MCP server for the One Piece Wiki. It gives any MCP client (Claude, Cursor, VS Code, Windsurf, Codex, Gemini CLI and others) structured access to articles, infoboxes, manga chapters, anime episodes and story arcs, plus a spoiler limit that keeps answers within what you've read.

Generic MediaWiki servers can fetch pages from this wiki too. This one knows how the One Piece Wiki is laid out, so it can return clean text instead of wikitext, read infobox fields as data, map chapters ↔ episodes ↔ arcs, and cut later-arc sections out of character histories.

Tools

The article tools take a title and follow redirects ("Zoro" → Roronoa Zoro). A title that differs from the article's only in case ("roronoa zoro") resolves to it; a title with no article returns up to three suggested titles. With a spoiler limit set, they withhold articles about subjects that debut past it (see below).

How the spoiler limit works

With a limit set (via set_spoiler_limit, or by default via ONEPIECE_SPOILER_CHAPTER):

• get_chapter, get_arc and list_arcs withhold anything that starts after the limit.

• get_episode is judged by the chapters it adapts. Filler is judged by the canon arc it airs during or, when it airs between canon arcs, the one it airs after.

• list_filler_arcs leaves out anime-only arcs whose canon arc starts after the limit; list_cover_stories leaves out serials whose first chapter is past it.

• get_page, get_page_sections, get_infobox, get_page_categories and list_subpages withhold articles whose subject first appears after the limit:

  • Chapter N and Episode N pages follow the get_chapter and get_episode rules, and canon arc pages (and saga pages made up only of later arcs) the get_arc rule.

  • Anything else is judged by the Debut field of its infobox: the first chapter listed, or for anime-only subjects the first chapter of the canon arc the anime had reached by the debut episode. Subjects that debuted in a film or game, or have no infobox, are not withheld.

  • Subpages such as Kaidou/History are judged by their base article.

• get_page removes sections headed by a later arc or saga, which is how every character History page is organised.

It cannot filter later facts mentioned in the intros, infoboxes (e.g. a current bounty) or prose outside arc headings of subjects that debuted earlier, and every affected response ends with a notice saying so. search_wiki and get_category_members are not filtered.

The limit is remembered. set_spoiler_limit saves the new value, including turning the limit off, to a small JSON state file (~/.config/mcp-onepiece/state.json by default; see ONEPIECE_STATE_FILE under Configuration), and the server loads it at startup. A saved value wins over ONEPIECE_SPOILER_CHAPTER, which only applies until you first set a limit. get_spoiler_limit reports the source: saved, environment, session (set while saving is off or failed) or null when there is no limit. The file is read only at startup, so servers running at the same time don't see each other's changes, and whichever saves last wins. If the file can't be written, the limit still applies for the session and the tool response says it wasn't saved.

Related MCP server: osrs-wiki-mcp

Install

Requires Node.js 20 or newer. There is nothing to clone or build: MCP clients start the server with npx, which downloads it from npm on first use.

Claude Code

claude mcp add -s user onepiece-wiki -- npx -y @wlahsib/mcp-onepiece

Claude Desktop, Cursor, Windsurf, Gemini CLI

These all use the same mcpServers format. Add this to the client's config file:

{
  "mcpServers": {
    "onepiece-wiki": {
      "command": "npx",
      "args": ["-y", "@wlahsib/mcp-onepiece"]
    }
  }
}

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json in a workspace, or run MCP: Add Server from the command palette:

{
  "servers": {
    "onepiece-wiki": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wlahsib/mcp-onepiece"]
    }
  }
}

OpenAI Codex CLI

codex mcp add onepiece-wiki -- npx -y @wlahsib/mcp-onepiece

Any other MCP client

The server speaks MCP over stdio. Point the client at the command npx -y @wlahsib/mcp-onepiece.

Setting a default spoiler limit

Pass ONEPIECE_SPOILER_CHAPTER in the client's environment settings, e.g. for the mcpServers format:

"onepiece-wiki": {
  "command": "npx",
  "args": ["-y", "@wlahsib/mcp-onepiece"],
  "env": { "ONEPIECE_SPOILER_CHAPTER": "1000" }
}

or claude mcp add -s user onepiece-wiki -e ONEPIECE_SPOILER_CHAPTER=1000 -- npx -y @wlahsib/mcp-onepiece. You can also just tell the assistant how far you've read; it calls set_spoiler_limit, and that limit is remembered for future sessions. Once a limit has been saved it takes precedence over ONEPIECE_SPOILER_CHAPTER.

Troubleshooting

• spawn npx ENOENT: desktop apps launched from the Dock or Start menu may not see your shell's PATH. Use the full path from which npx (macOS/Linux) as command. On Windows, use "command": "cmd", "args": ["/c", "npx", "-y", "@wlahsib/mcp-onepiece"].

• Picking up a new version: npx caches packages; use npx -y @wlahsib/mcp-onepiece@latest to force an update.

Running from source

git clone https://github.com/bishalw/mcp-onepiece.git && cd mcp-onepiece
npm install && npm run build

Then use node /absolute/path/to/mcp-onepiece/dist/index.js as the command in any of the configs above.

Configuration

All settings are optional environment variables.

Invalid values stop the server at startup with a message naming the variable.

Development

npm run dev              # run from source with tsx
npm run check            # typecheck + lint + tests
npm run build            # compile to dist/
npm run inspect          # open the MCP Inspector against dist/
npm run fixtures:record  # re-record test fixtures from the live wiki

Releasing

npm version patch        # or minor / major; commits and tags
npm publish              # prepublishOnly runs all checks and a fresh build first
git push --follow-tags

The published package contains only dist/*.js, README.md and package.json. The server and the wiki User-Agent both read their version from package.json.

Layout

src/
  index.ts          entry point: config, logging, stdio transport, shutdown
  state.ts          state file that remembers the spoiler limit between sessions
  version.ts        package name and version, read from package.json
  server.ts         createServer(): wires the client, domain services and tools
  config.ts         environment parsing and validation (zod)
  wiki/             MediaWiki API client: cache, concurrency limit, timeouts, retries, title fallback
  parsing/          HTML → text, infobox and range parsing (pure functions)
  domain/           arcs catalog, filler arcs and cover stories, chapters/episodes, spoiler guard
  tools/            MCP tool definitions, thin adapters over domain/
test/
  unit/             parsing, cache, limiter, client, config, spoiler guard, filler/cover-story parsing
  integration/      MCP client ↔ server over an in-memory transport, replaying fixtures; spoiler-limit persistence
  support/          fixture record/replay, test harness, scenarios
  fixtures/         recorded wiki API responses
scripts/
  record-fixtures.ts

Tests and fixtures

Integration tests drive the real server through an MCP client, but the wiki is replaced by responses recorded in test/fixtures. Tests never touch the network, and a request with no recorded fixture fails with a message telling you to re-record. They also run with the state file turned off (persistence tests use temp directories), so they never touch your saved spoiler limit. npm run fixtures:record runs every entry in test/support/scenarios.ts against the live wiki and rewrites the fixtures. Do this after adding a scenario, or when the wiki's markup changes and you want to confirm the parsers still work.

Design notes

• Parsing rendered HTML instead of wikitext. Infobox values such as arc chapter ranges are computed by templates (chapter = auto), so only the rendered page has them.

• Stable keys. Infobox fields are read by their data-source template parameter rather than by display label.

• Polite by default. Requests use a descriptive User-Agent, bounded concurrency, caching, and exponential backoff that honours Retry-After.

• Errors the model can act on. Missing pages, unknown arcs and spoiler blocks are returned as tool errors with a next step. Unexpected failures are logged to stderr and summarised.

Licence

The code is released under the MIT License.

Wiki content

Wiki content is © One Piece Wiki contributors under CC BY-SA. Tool responses include article URLs so answers can link their sources.