wikijs-graphql-mcp

唯讀的 Wiki.js 2.x MCP server。透過 Wiki.js GraphQL API 搜尋、瀏覽與讀取頁面，讓 AI 助理能查詢公司知識庫。

• 只提供唯讀 tools：沒有任何建立、更新、移動或刪除頁面的能力；GraphQL client 也會拒絕送出 mutation／subscription。

• 不需要登入流程：在 MCP 設定中直接提供 Wiki.js API Key 即可。

npm 套件名稱為 wikijs-graphql-mcp，GitHub repository 為 vanisoul/wikijs-mcp。registry npx 範例需等套件實際發布到 npm 後才能使用；原始碼開發與 tarball 驗證不需要先發布。

快速開始：npx 設定 MCP

需求：Node.js 22 或更新版本，以及支援 stdio 的 MCP Client。

{
  "mcpServers": {
    "wikijs": {
      "command": "npx",
      "args": ["--yes", "wikijs-graphql-mcp@0.1.0"],
      "env": {
        "WIKIJS_BASE_URL": "https://wiki.example.com",
        "WIKIJS_API_TOKEN": "YOUR_WIKIJS_API_KEY",
        "WIKIJS_LOCALE": "zh-tw"
      }
    }
  }
}

完整設定範例位於 examples/mcp.json。

取得 API Key

1. 以管理員登入 Wiki.js，進入 管理 → API 存取，確認 API 已啟用。

2. 建立新的 API Key，群組請選擇只有讀取權限的群組（例如僅具 read:pages、read:source 的群組），落實最小權限。

3. 將 Key 填入 MCP 設定的 WIKIJS_API_TOKEN。API Key 的頁面可見範圍依所屬群組的頁面規則而定。

Pi

把設定放在使用者的 ~/.pi/agent/mcp.json，或受信任專案的 .pi/mcp.json（已列入 .gitignore，避免 API Key 進入版本控制）。也可以執行：

pi mcp add wikijs \
  --env WIKIJS_BASE_URL=https://wiki.example.com \
  --env WIKIJS_API_TOKEN=YOUR_WIKIJS_API_KEY \
  -- npx --yes wikijs-graphql-mcp@0.1.0

專案限定設定使用 pi mcp add -l。設定完成後執行 /reload 或重新啟動 Pi。

其他 MCP Client

使用相同的 command、args 與 env。設定檔路徑與重新載入方式依 Client 而定。Windows Client 若無法直接找到 npx，可依該 Client 的程序啟動方式改用 npx.cmd。

Related MCP server: WikiJS MCP Server

CLI

wikijs-graphql-mcp               啟動 stdio MCP server
wikijs-graphql-mcp serve         啟動 stdio MCP server
wikijs-graphql-mcp --version     顯示套件版本
wikijs-graphql-mcp --help        顯示用法與環境變數

缺少 WIKIJS_BASE_URL 或 WIKIJS_API_TOKEN 時，server 會在啟動時以錯誤訊息結束。

Tools

所有 tools 都標記 readOnlyHint: true、destructiveHint: false。

建議流程：先用 wikijs_search_pages 或 wikijs_browse_tree 找到頁面路徑，再用 wikijs_get_page 讀取內容。

行為說明

• 頁面路徑：不含開頭斜線與 .md，可含中文，例如 RD部/Projects/690_整合式專利檢索系統/資料轉置/DOCDB/docdb-status。工具會自動移除多餘的斜線、.md 與 URL 編碼；也可以直接貼上同站台網址，如 https://wiki.example.com/zh-tw/RD部/...，網址中的語系段會自動套用。

• 找不到頁面：Wiki.js 對不存在的頁面會回傳 GraphQL 錯誤（code 6003）而非 null；本 server 會轉成 { "found": false, ... } 的一般結果，不視為錯誤。API Key 沒有讀取權限的頁面也會呈現為找不到。

• 長頁面：wikijs_get_page 預設最多回傳 100,000 字元，並提供 contentLength、truncated、nextContentOffset；以 contentOffset 接續讀取下一段。

• 路徑前綴過濾：Wiki.js search(path) 參數實測並非前綴比對，因此 pathPrefix 一律在取得結果後於本地端以路徑段落比對（不分大小寫）。wikijs_list_pages 指定 pathPrefix 時需要取得完整頁面清單再過濾，大型站台會稍慢。

• 搜尋結果不含頁面 ID：實測 Wiki.js 搜尋索引回傳的 ID 可能與實際頁面 ID 不一致（索引未同步），因此搜尋結果只提供可靠的 path／locale，讀取時以路徑為準。

• 頁面樹：Wiki.js 的 tree(path) 回傳的是節點的「同層」項目，本 server 會先定位節點，再查詢其子項目。資料夾若本身也有頁面，hasPage 為 true。

設定與安全性

• API Key 只透過 Authorization: Bearer header 送往 WIKIJS_BASE_URL/graphql，不會出現在 tool 結果或錯誤訊息中。

• 請求停用 redirect，並設有逾時；WIKIJS_BASE_URL 不接受帳密、查詢參數或錨點。

• 所有 GraphQL 操作皆為寫死在程式中的 query，executor 另外會拒絕任何非 query 的操作，作為唯讀的第二道防線。

• 無效或權限不足的 API Key 會收到 Forbidden，錯誤訊息會提示檢查 WIKIJS_API_TOKEN。

• 建議為 MCP 建立專用、只具讀取權限的 API Key，並設定到期日。

相容性與限制

• 適用 Wiki.js 2.x GraphQL API（pages.search、pages.singleByPath、pages.single、pages.list、pages.tree、pages.tags）。Wiki.js 3.x 的 API 不同，未支援。

• 搜尋品質與結果數量取決於站台設定的搜尋引擎（Basic DB、PostgreSQL、Elasticsearch 等），Wiki.js 搜尋 API 不支援伺服器端分頁。

• 不提供頁面建立、編輯、移動、刪除、渲染或歷史版本還原等寫入能力。

原始碼開發與發布

npm ci
npm run check
npm run test:package
npm run check:release

開發時可使用 node dist/cli.js 啟動 MCP，並在 Client 的 env 設定 WIKIJS_BASE_URL 與 WIKIJS_API_TOKEN。examples/mcp.json 是可公開的設定範例；個人 .pi/mcp.json 不納入版本控制。

測試包含：

• test/wikijs.test.mjs：設定驗證、路徑工具、唯讀保護、GraphQL 錯誤處理與 client 行為。

• test/server.test.mjs：以 stdio 啟動 MCP，對模擬 Wiki.js GraphQL server 驗證所有 tools，並確認只提供唯讀 tools、所有請求皆為 query。

• test/release*.test.mjs、test-package/：發布流程與 npm 套件 manifest 檢查。

npm 只打包 dist/、examples/、README、LICENSE 等明確允許的檔案。prepack 會建置，prepublishOnly 會檢查必須在 main、執行測試；使用者安裝 registry 套件時不需要 TypeScript 開發依賴。

GitHub Trusted Publishing

正式發布從已合併至 main 的版本 Tag 進行，workflow 位於 .github/workflows/publish.yml。推送符合 v* 的 Tag 後，流程會：

1. 驗證 Tag 與 package.json 版本一致、Tag commit 位於 main 歷史中。

2. 在沒有 OIDC 發布權限的 verify job 執行測試、建置及打包。

3. 記錄 tarball 的 SHA-512、來源 commit、名稱與版本，並上傳 artifact。

4. 在獨立 publish job 下載同一份 artifact，重新檢查中繼資料與 SHA-512。

5. 清除長效 Token 與既有 npm config，改用暫存設定及工作目錄。

6. 使用 GitHub OIDC 短期憑證執行 npm publish VERIFIED_TARBALL --access=public --provenance=true，直接正式上架 npm。

npm Trusted Publisher 設定：

• GitHub repository：vanisoul/wikijs-mcp，workflow filename：publish.yml。

• npm 套件：wikijs-graphql-mcp。

• Environment name 留空；Allowed action 必須允許直接 npm publish。

• publish job 使用 id-token: write 與 GitHub-hosted runner；不需要 NPM_TOKEN secret。

Trusted Publisher 設定是逐套件管理，全新套件需先確認該帳號支援的初始化方式。

發布版本

package.json 0.1.0 → git tag v0.1.0

本機先驗證：

git switch main
npm ci
npm run check
npm run test:package
npm run check:release
npm pack --dry-run

確認發布權限後再建立並推送 Tag：

git tag -a v0.1.0 -m "release: v0.1.0"
git push origin main
git push origin v0.1.0

不要移動或強制覆寫已推送的 Tag；修正請使用新版本號。

授權

MIT，詳見 LICENSE。