Wiki.js

wikijs-mcp

一个用于 Wiki.js 的模型上下文协议（MCP）服务。Wiki.js 是一款可自托管的 Wiki，以 Markdown 保存页面，并通过一个 GraphQL 端点提供所有功能。

它让 Claude Code、Claude Desktop 或 Codex 等 MCP 客户端能够搜索、阅读和编辑 Wiki 页面；如果你允许，还可以管理资源、评论、用户、群组和维护任务。

62 个工具只是上限，而不是必选项： WIKIJS_ALLOW_TOOLS=essential 会改为注册精心挑选的 7 个工具，而模型从 7 个工具中挑选正确工具，远比从 62 个工具中可靠——请参阅选择要加载的工具。

有何不同

能找到文本搜索找不到的内容。 Wiki.js 的默认引擎只索引标题和描述，因此 search_pages 会说明当前使用的搜索引擎，而 grep_pages 会搜索页面中的实际文本。

不会覆盖同事的修改。 update_page 会比对你读取页面时的内容；如果期间保存了其他编辑，它会拒绝覆盖。精确编辑必须且只能匹配一次。

可将写入限制在 Wiki 的部分路径中。 WIKIJS_ALLOWED_PATHS 会将写入页面和资源的工具限制在指定路径前缀内，并按路径片段匹配；读取不受限制。

要求

• Node.js ≥ 22
• 正在运行的 Wiki.js 实例和 API 令牌

配置

变量	必填	描述
WIKIJS_URL	是	Wiki 的基础 URL，例如 https://wiki.example.com。末尾的 /graphql 会被去除
WIKIJS_TOKEN	是	来自 Administration → API Access 的 API 密钥。也接受 WIKIJS_API_KEY 作为别名
WIKIJS_LOCALE	否	未指定语言环境的页面工具默认使用的语言环境（默认值为 en）
WIKIJS_READ_ONLY	否	true、1 或 yes 仅注册读取工具
WIKIJS_ALLOWED_PATHS	否	写入工具可操作的页面路径前缀，以逗号分隔，例如 docs,team/notes
WIKIJS_ALLOW_TOOLS	否	工具名称、list_* 前缀，或用于精选预设的 essential，以逗号分隔
WIKIJS_DENY_TOOLS	否	语法相同；从 WIKIJS_ALLOW_TOOLS 保留的工具中移除
ELICITATION	否	false 会用双调用令牌替代审批对话框。不带前缀
WIKIJS_INSECURE_TLS	否	true 接受自签名证书（仅对当前连接生效）

语言环境是页面身份的一部分，而非显示偏好：en 和 de 下的同一路径代表两个不同的页面。如果 Wiki 使用其他语言，请设置 WIKIJS_LOCALE，否则所有按路径进行的查找都会返回“未找到”。list_locales 会报告已安装的语言环境。

API 密钥具有管理权限。 Wiki.js 提供“完全访问权限”或按组授权；拥有完全访问权限的密钥可以重写所有页面和账户。WIKIJS_READ_ONLY、WIKIJS_ALLOWED_PATHS 和密钥自身的组权限是三种相互独立的限制方式——请参阅 SECURITY.md。

请使用 https://。 使用普通 http 时，令牌会以未加密形式传输；除非主机位于本地，否则服务器会打印警告。对于自签名证书，建议优先使用正规的内部 CA，而不是 WIKIJS_INSECURE_TLS。

即使没有凭据，服务器仍会启动并列出其工具（以便注册表和检查器进行检查），但所有调用都会失败并显示设置说明，而不会访问 API。

选择要加载的工具

WIKIJS_ALLOW_TOOLS 和 WIKIJS_DENY_TOOLS 接受以逗号分隔的工具名称；末尾的 * 可匹配整个类别。essential 是精选预设，包含 search_pages、grep_pages、get_page、list_pages、get_page_tree、create_page 和 update_page，足以端到端地查找、读取和写入 Wiki 页面；工具参考文档中也将其标记为精选预设，详见 工具参考。

WIKIJS_ALLOW_TOOLS=essential
WIKIJS_ALLOW_TOOLS=get_page,search_pages,list_*
WIKIJS_DENY_TOOLS=delete_*,purge_page_history,set_api_state

若某个条目未匹配到任何工具，服务器会中止启动并指出该条目，因此拼写错误不会悄悄隐藏工具——否则没人会想到要从环境变量入手查找工具缺失的原因。经过筛选的工具不会被注册，因此它们既不会出现在 tools/list 中，也无法通过 tools/call 调用，这与 WIKIJS_READ_ONLY 下的写入工具完全相同。

如果同时运行多个此类服务器，另一个解决方案是 mcp-hub——其 /hub 端点会用六个元工具替代每个服务器的所有工具。

将写入限制在 Wiki 的部分区域

WIKIJS_ALLOWED_PATHS 会将写入页面和资源的工具限制在一组路径前缀内。 读取仍不受限制，这是有意为之：限制读取范围会让 Wiki 变得支离破碎、令人困惑；而 API 密钥自身的页面规则才是彻底隐藏页面的正确方式——它们也会在 Web UI 中隐藏页面。

WIKIJS_ALLOWED_PATHS=docs,team/notes

匹配按路径段进行，因此 docs 会涵盖 docs/setup，但不会涵盖 docs-archive/old。move_page 会检查移动的起点和终点，因此页面既不能移出 允许区域，也不能移入受保护区域。

资源写入会根据资源文件夹树进行检查，该命名空间是独立的。无法通过前缀限制的操作——所有六个实例级维护工具、标签工具，以及评论编辑（因为 Wiki.js 不会说明评论属于哪个页面）——会在设置该变量时拒绝执行，而不是悄悄例外处理。这包括 flush_page_cache、rebuild_page_tree 和 rebuild_search_index：它们不会丢失任何内容，但仍会作用于整个 Wiki。

安装

Claude Code

claude mcp add wikijs-mcp -- npx -y @ni-c/wikijs-mcp

Claude Desktop

{
  "mcpServers": {
    "wikijs-mcp": {
      "command": "npx",
      "args": ["-y", "@ni-c/wikijs-mcp"],
      "env": {
        "WIKIJS_URL": "https://wiki.example.com",
        "WIKIJS_TOKEN": "…"
      }
    }
  }
}

Codex

[mcp_servers.wikijs-mcp]
command = "npx"
args = ["-y", "@ni-c/wikijs-mcp"]
env = { WIKIJS_URL = "https://wiki.example.com", WIKIJS_TOKEN = "…" }

Docker

docker run --rm -i \
  -e WIKIJS_URL=https://wiki.example.com \
  -e WIKIJS_TOKEN=… \
  ghcr.io/ni-c/wikijs-mcp

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、Claude on the web、 Cursor、LibreChat——可通过 mcp-hub 连接 wikijs-mcp：一个 容器可通过 Streamable HTTP 服务多个 stdio MCP 服务，并在单个密码后提供 OAuth 2.1 登录，还为无法使用 OAuth 的客户端提供长期令牌。其 /hub 端点会通过六个元工具接入所有服务，因此一个连接器即可连接所有服务，而无需在模型上下文中放入 N×工具架构；它还能使用两个协议修订版本——本服务提出的问题会经由它传递给另一端的人员。

其 /config/mcp.json 使用 Claude Code 的格式，因此配置项就是你已有的那一项：

{
  "mcpServers": {
    "wikijs-mcp": {
      "command": "npx",
      "args": ["-y", "@ni-c/wikijs-mcp"],
      "env": {
        "WIKIJS_URL": "https://wiki.example.com",
        "WIKIJS_TOKEN": "…",
        "WIKIJS_ALLOW_TOOLS": "essential"
      },
      "denyTools": ["delete_*,purge_page_history,set_api_state"]
    }
  }
}

其中的 allowTools 和 denyTools 是 hub 自身针对每个服务的过滤器，与 env 中的 *_ALLOW_TOOLS 并不相同——两者的区别以及容易由此引发的错误，详见 客户端指南。

工具

共有 62 个工具。★ 标记 essential 预设中的工具；⚠ 标记会通过 MCP elicitation 向人员发起询问的工具——模型无法代替人员回答的对话；如果客户端无法显示此类对话，则会退回到两次调用的 confirm_token。请参阅 向人员发起询问。

每个工具都声明了一个 outputSchema，并在文本块之外通过 structuredContent 返回结果，因此客户端无需解析散文即可使用结果。 29 个原本只返回一句话的工具——“已删除页面 5（路径）。”—— 现在也会返回相应字段，而这句话仍会保留在读者希望看到的位置。

报告 Wiki 内容的工具会携带 untrusted: true 和 source: "wikijs" 字段；页面文本、标题、描述和评论均由拥有编辑权限的人员撰写。列表根据调用点确定：只有当工具已经通过不可信内容包装器处理其答复时，才会对其进行标记。

update_page 对过时读取的拒绝会保留原有形式，作为有意设置的例外——它仍是普通结果，而不是错误，因为它给出的是恢复操作的指引，而非失败信息；现在它还会在字段中给出 written: false 和两个时间戳。

工具	描述
list_pages	★ 列出页面及其元数据，默认按时间从新到旧排序。
get_page	★ 读取一个页面，可通过 page_id 或路径加区域设置来指定。
search_pages	★ 全文搜索——但请先阅读此说明：在默认配置的 Wiki.js 中，搜索引擎为“Database - Basic”，它只会为页面标题和描述编制索引，不会为页面正文编制索引。
grep_pages	★ 通过获取页面并在本地匹配正则表达式，搜索页面的实际文本。
get_page_tree	★ 列出路径下的直接子页面和文件夹——呈现维基的结构视图，而搜索无法做到这一点。
list_page_links	返回每个页面及其包含的内部链接——展示某个区域设置下维基的链接图谱。
create_page	★ 创建页面。
update_page	★ 修改页面。
move_page	将页面移至其他路径、其他区域设置，或同时更改两者。
delete_page	⚠ 删除页面及其历史记录。
convert_page_editor	更改页面的存储格式。
list_page_history	列出页面存储的版本，按时间从新到旧排序，并显示修改者、修改内容和修改时间。
get_page_version	返回页面的一个历史版本，包括该版本当时的完整正文。
diff_page_versions	返回页面两个版本之间的统一差异；若省略 to_version，则返回一个版本与页面当前内容之间的差异。
get_page_conflict	返回比你读取的版本更新的页面版本——update_page 拒绝写入时所指向的版本。
restore_page_version	将页面回滚到已存储的版本。
list_tags	列出维基中的所有标签及其显示标题和最近使用时间。
search_tags	查找与片段匹配的标签。
update_tag	更改标签名称或显示标题，并应用到所有带有该标签的页面。
delete_tag	⚠ 从维基以及所有带有该标签的页面中移除该标签。
list_assets	列出某个资源文件夹中的图片和文件。
list_asset_folders	列出某个资源文件夹下的直接子文件夹。
upload_asset	将图片或文件上传到资源文件夹，以便嵌入页面。
create_asset_folder	在资源存储中创建文件夹。
rename_asset	重命名资源。
delete_asset	⚠ 永久删除资源。
list_comments	返回某个页面的评论，通过路径和区域设置指定页面，而非页面 ID；这是 Wiki.js 要求使用路径而不是页面 ID 的唯一场景。
get_comment	根据 ID 返回单条评论，包括其源文本和渲染后的 HTML。
create_comment	在页面上发布评论，也可选择回复另一条评论。
update_comment	替换评论正文。
delete_comment	⚠ 永久删除评论。
list_users	列出维基的用户账号。
search_users	按姓名或电子邮件查找用户。
get_user	返回单个账号的完整详情，包括其所属群组以及是否启用了双重身份验证。
create_user	创建账号。
update_user	更改账号详情或其群组成员身份。
delete_user	⚠ 删除账号。
set_user_active	启用或停用账号。
verify_user	将账号的电子邮件标记为已验证；通常用户需要点击链接才能完成验证。
set_user_tfa	启用或停用账号的第二重验证。
reset_user_password	为本地账号启动 Wiki.js 自带的密码重置流程，并向用户发送含有链接的电子邮件。
list_groups	列出维基的群组及各群组的用户数量。
get_group	返回一个群组及其全局权限、页面规则和成员。
create_group	创建空群组。
update_group	完整替换群组名称、权限和页面规则——这不是部分更新，省略某条规则会将其删除。
delete_group	⚠ 删除群组。
assign_user_to_group	将一个账号添加到一个群组，同时保留其其他群组成员身份——这是 update_user 的群组列表更新操作的增量对应项。
unassign_user_from_group	将一个账号从一个群组中移除。
get_site_info	返回版本、数据库和主机摘要，以及站点自身的标题和描述，并提供页面、用户、群组和标签的总数。
list_locales	列出已安装的区域设置以及默认区域设置。
get_navigation_tree	返回按区域设置配置的侧边栏导航。
list_search_engines	返回此维基使用的搜索引擎。
list_api_keys	列出维基的 API 密钥及其到期时间、是否已撤销，以及 API 访问是否已启用。
list_storage_targets	列出已配置的存储后端——Git 镜像、S3 存储桶、本地文件转储等——及其同步状态和最近的错误。
revoke_api_key	⚠ 立即永久撤销 API 密钥——Wiki.js 无法恢复已撤销的密钥。
set_api_state	⚠ 启用或停用 Wiki.js 的整个 API。
render_page	强制 Wiki.js 根据源内容重新生成一个页面的 HTML。
flush_page_cache	清除整个维基的 Wiki.js 页面渲染缓存。
rebuild_page_tree	重新计算 Wiki.js 根据页面路径生成的文件夹结构。
rebuild_search_index	在当前使用的搜索引擎中为所有页面重新编制索引。
purge_page_history	⚠ 删除整个维基中早于指定截止时间的页面存储版本。
migrate_pages_locale	⚠ 将整个维基的所有页面从一个区域设置迁移到另一个区域设置。
完整参考文档（含所有参数）请参阅
wikijs-mcp.ni-c.de/reference/tools。

使用 search_pages 前值得了解的两件事

Wiki.js 的默认搜索引擎不会索引页面内容。“Database - Basic”只会匹配标题和描述，因此搜索页面内写的短语时，完全不会返回结果。search_pages 会报告当前使用的引擎并说明这一点；grep_pages 会获取页面并在本地匹配文本，速度较慢，但确实能找到内容。将 wiki 切换到 PostgreSQL 或 Elasticsearch 引擎并运行 rebuild_search_index，即可妥善解决此问题。

**update_page 不会覆盖其他人所做的编辑。**它会将页面与_你_读取页面时的状态进行比较，而不是与它自己早一毫秒读取的状态比较，因此，如果模型思考期间有人通过网页 UI 保存了编辑，这些编辑会被发现，而不会被悄悄丢弃。get_page_conflict 会显示较新的版本；force: true 则会按预期覆盖。

有意不提供的功能

**没有创建 API 密钥的工具。**Wiki.js 可以通过 GraphQL 创建密钥，但此服务刻意不提供此功能：能够生成完全访问权限密钥的模型，可能会给自己授予上述三种限制机制所移除的所有权限。

读取操作从不按路径限制。WIKIJS_ALLOWED_PATHS 只限制写入——限制读取范围会让 wiki 变成令人困惑的半成品，而密钥自身的用户组和页面规则才是隐藏页面的合适位置，因为这些规则也适用于其他所有使用该密钥的操作。

安全性

• **破坏性和管理类工具需要用户确认。**如果客户端支持 MCP elicitation，这些工具会弹出模型无法代为回答的真实对话框。如果不支持，首次调用会返回一个短时有效、绑定到确切目标的令牌；只有第二次调用携带该令牌时才会执行操作——这只能证明使用相同参数进行了两次调用，不代表更多信息，提示文本也会明确说明这一点。绑定范围涵盖所有决定_操作对象_的内容——针对 migrate_pages_locale 从 de 迁移到 en 的批准，不会执行从 en 迁移到 de。将 ELICITATION=false 设置为有意使用后备机制；它绝不会移除防护。
• 三种维护工具有意不设置确认门槛。flush_page_cache、rebuild_page_tree 和 rebuild_search_index 消耗的是时间，而不是内容。对不会造成任何损失的操作设置确认对话框，只会让人学会不看内容就勾选确认。
• **确认提示绝不引用 Wiki.js 中的内容。**页面标题和描述可由任何拥有编辑权限的人编写，而这些文本会被模型读取。提示中只会出现 ID、路径和服务端值，并且路径在插入前会经过标识符校验。
• 返回的页面内容会被标记为不可信数据，因为 wiki 正是用于存储文本、供日后阅读的地方。
• 没有创建 API 密钥的工具，尽管 Wiki.js API 提供此功能：能够生成完全访问权限密钥的模型，可能会授予自己超出当前会话有效期的管理权限。这里提供了 list_api_keys 和 revoke_api_key，以便审计和撤销密钥。
• 启动后会从环境中删除凭据，API 响应中的密钥会被删去，错误正文会被截断，HTML 错误页面会被丢弃。
• WIKIJS_READ_ONLY=true 完全不会注册写入工具，而 WIKIJS_DENY_TOOLS 则可按相同原则进行更细粒度的限制——被过滤的工具根本不会被构建，而不是在调用时被拒绝。

文档

完整指南、工具参考和安全说明请参阅 wikijs-mcp.ni-c.de（源文件位于 docs/）。

开发

npm install
npm run lint && npm run typecheck && npm run build && npm test

单元测试套件会通过真实的 MCP 协议，使用模拟的 Wiki.js 测试构建后的服务，因此无需运行任何实例；npm run test:integration 是独立的测试套件，会在 Docker 中启动真实的 Wiki.js，并针对它测试每个工具。架构图和社交卡片均为生成文件——编辑 docs/assets/architecture.source.svg 并运行 npm run assets，切勿修改渲染后的副本——npm run docs:tools 则会根据目录重新生成工具参考文档。

发布

1. 添加 CHANGELOG 条目并更新 package.json 中的版本号。
2. npm run lint && npm run build && npm run test:coverage
3. 提交，然后推送已签名的标签：git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z

发布工作流会将软件包发布到 npm（使用 Trusted Publishing，并附带来源证明）、根据 CHANGELOG 中的章节创建 GitHub 发布，并更新 MCP Registry 条目。

贡献

欢迎提交问题、参与讨论和发起拉取请求——请参阅 CONTRIBUTING.md。如需报告漏洞，请使用 私密报告渠道， 而非公开问题；相关政策见 SECURITY.md。

许可证

MIT © Willi Thiel