使用说明

Wiki.js MCP服务器

全面 模型上下文协议（MCP）服务器 Wiki.js——24个工具，双传输（stdio+HTTP/SSE），为生产自托管基础设施构建。

连接 克劳德桌面版 或任何与MCP兼容的客户端直接连接到您的Wiki.js实例。阅读页面、创建结构化文档、同步代码更改、管理层次结构——所有这些都是通过自然语言完成的。

🎯 这有什么作用

连接后，您可以要求Claude：

🔍 搜索任何主题的wiki
📖 阅读按路径或ID显示任何页面
✏️ 创建和更新 文档
🗂️ 组织通过移动页面
🏗️ 脚手架 完整的回购文档结构
🔗 同步链接wiki页面的源代码更改
🗑️ 清理过时的页面和层次结构

🚀 快速开始

先决条件

python 3.11+ --兼容高达 3.14 （3.12推荐）
跑步 Wiki.js 实例（v2.x）
Wiki.js API密钥 具有完全访问权限（请参见获取API密钥)

为Claude Code安装（推荐通过 `uvx`)

没有克隆，就没有病毒。需要 uv 在每台Mac上。每个用户都在本地运行服务器 自己的 Wiki.js API密钥，因此保留每个用户的权限：

claude mcp add wikijs \
  --env WIKIJS_URL=https://your-wiki.example.com \
  --env WIKIJS_API_KEY=your_api_key_here \
  -- uvx wiki-js-mcp-server@latest

uvx 从PyPI获取包并运行它——无需安装或维护。证实 “检查我的Wiki.js连接状态”；回复包括 server_version 现场。

更新--选择您的策略：

配置参数	行为
`uvx wiki-js-mcp-server@latest`	总是最新的。每次重新启动Claude Code都会重新解析PyPI并自动获取新版本。
`uvx wiki-js-mcp-server@1.1.0`	钉。在编辑版本之前，永远不要更改。
`uvx wiki-js-mcp-server`	使用任何东西 `uvx` 缓存；跑 `uv cache clean wiki-js-mcp-server` 强制刷新。

因为每台Mac都运行自己的进程， WIKIJS_API_KEY 每个用户保留一个Mac，一个Wiki.js用户，一个密钥。

已经安装了git clone？ 看 docs/MIGRATION-uvx.md 切换到 uvx --macOS/Linux的分步操作 和Windows.

从源代码安装（克劳德桌面/开发）

git clone https://github.com/2rock-Inc/wiki-js-mcp-server.git
cd wiki-js-mcp-server
chmod +x setup.sh start.sh
./setup.sh

安装脚本创建一个Python虚拟环境并安装所有依赖项。

2.配置

编辑 .env 在项目根：

WIKIJS_URL=https://your-wiki.example.com
WIKIJS_API_KEY=your_api_key_here

⚠️ 对于Claude Desktop（stdio模式）很重要： 使用 绝对路径 为了 WIKIJS_MCP_DB 和 LOG_FILE.Claude Desktop从启动进程 /，因此相对路径将失败。

WIKIJS_MCP_DB=/absolute/path/to/wiki-js-mcp-server/wikijs_mappings.db
LOG_FILE=/absolute/path/to/wiki-js-mcp-server/wikijs_mcp.log

3.配置克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "wikijs": {
      "command": "/absolute/path/to/wiki-js-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/wiki-js-mcp-server/src/server.py", "--stdio"]
    }
  }
}

重新启动克劳德桌面→ 设置→ 开发者 → 你应该看看 wikijs 带着一个🟢 绿点和列出的24种工具。

4.验证连接

问克劳德： “检查我的Wiki.js连接状态” 或 “列出我的wiki中的所有页面”.

📊 MCP工具（共24个）

🔧 连接

工具	说明
`wikijs_connection_status`	检查连接和身份验证运行状况

📝 核心页面管理

工具	说明
`wikijs_create_page`	使用可选路径或父级创建新页面
`wikijs_get_page`	按ID或路径检索页面（带内容大小控件）
`wikijs_get_page_metadata`	仅检索页面元数据——无内容，始终快速
`wikijs_update_page`	更新内容、标题、描述或标签
`wikijs_delete_page`	按ID或路径删除页面
`wikijs_move_page`	将页面移动到新路径或区域设置
`wikijs_search_pages`	带回退列表过滤器的全文搜索
`wikijs_list_pages`	列出所有包含元数据的页面
`wikijs_get_tree`	获取完整的页面树结构

🏗️ 分层文档

工具	说明
`wikijs_get_page_children`	列出页面的直接子项
`wikijs_create_nested_page`	在路径下创建页面，自动创建父级
`wikijs_create_repo_structure`	构建完整的存储库文档结构
`wikijs_create_documentation_hierarchy`	自动将项目文件组织到分类文档中

🗂️ 空间与组织

工具	说明
`wikijs_list_spaces`	列出顶级文档空间
`wikijs_create_space`	创建新的顶级空间

🗑️ 删除和清理

工具	说明
`wikijs_batch_delete_pages`	按ID、路径或全局模式删除多个页面
`wikijs_delete_hierarchy`	删除整个页面层次结构

🔗 文件↔页面同步（代码/文档集成）

工具	说明
`wikijs_link_file_to_page`	保持源文件和wiki页面之间的链接
`wikijs_sync_file_docs`	将更改注释附加到文件的链接wiki页面
`wikijs_generate_file_overview`	自动生成Python源文件的文档
`wikijs_bulk_update_project_docs`	将多个更改的文件批量同步到其wiki页面
`wikijs_cleanup_orphaned_mappings`	删除已删除wiki页面的映射
`wikijs_repository_context`	显示当前仓库上下文和活动映射

📄 处理大页面

带有嵌入式图像（base64内联）的Wiki.js页面可能会超过MCP响应大小限制。有两个工具可以解决这个问题：

wikijs_get_page 现在接受：

include_content=False --仅返回元数据，不返回内容
max_content_chars=800000 --在约800KB处自动截断并发出警告

wikijs_get_page_metadata --始终快速，返回尺寸信息：

{
  "pageId": 8,
  "title": "Proxmox",
  "content_size_kb": 2400.5,
  "has_large_content": true,
  "tip": "Use wikijs_get_page with include_content=False..."
}

🐳 Docker部署（远程HTTP模式）

Docker镜像发布在Docker Hub上，无需构建。

1.在服务器上部署

mkdir wiki-js-mcp && cd wiki-js-mcp
curl -O https://raw.githubusercontent.com/2rock-Inc/wiki-js-mcp-server/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/2rock-Inc/wiki-js-mcp-server/main/config/example.env
cp example.env .env
nano .env
docker compose up -d
docker compose logs -f

.env 对于Docker模式：

WIKIJS_URL=http://your-wiki-internal-ip:8090
WIKIJS_API_KEY=your_api_key_here
MCP_TRANSPORT=http
HTTP_HOST=0.0.0.0
HTTP_PORT=8000
WIKIJS_MCP_DB=/app/data/wikijs_mappings.db
LOG_FILE=/app/data/wikijs_mcp.log

2.Nginx反向代理

server {
    listen 443 ssl;
    server_name mcp-wiki.your-domain.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    auth_basic "Wiki MCP";
    auth_basic_user_file /etc/nginx/.htpasswd-mcp;

    location / {
        proxy_pass http://your-server:8000;
        proxy_http_version 1.1;

        # Required for SSE / streaming
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
        proxy_read_timeout 3600s;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

htpasswd -c /etc/nginx/.htpasswd-mcp your-user
nginx -t && systemctl reload nginx

3.克劳德桌面配置（HTTP模式）

{
  "mcpServers": {
    "wikijs": {
      "type": "http",
      "url": "https://mcp-wiki.your-domain.com/mcp",
      "headers": {
        "Authorization": "Basic <base64(user:password)>"
      }
    }
  }
}

生成base64值：

echo -n "user:password" | base64

⚙️ 环境变量

变量	默认值	描述
`WIKIJS_URL`	`http://localhost:3000`	Wiki.js基本URL
`WIKIJS_API_KEY`	-	API密钥（完全访问）
`WIKIJS_GRAPHQL_ENDPOINT`	`/graphql`	GraphQL端点路径
`MCP_TRANSPORT`	`stdio`	`stdio` 或 `http`
`HTTP_HOST`	`0.0.0.0`	HTTP绑定地址
`HTTP_PORT`	`8000`	HTTP侦听端口
`WIKIJS_MCP_DB`	`./wikijs_mappings.db`	SQLite数据库文件↔页面映射
`LOG_FILE`	`./wikijs_mcp.log`	日志文件路径(在stdio模式下使用绝对路径)
`WIKIJS_DEFAULT_LOCALE`	（空）	创建/读取页面的区域设置。空=自动检测wiki自己的默认区域设置；设置（例如。 `en`, `fr`)强迫一个
`LOG_LEVEL`	`INFO`	`DEBUG` / `INFO` / `WARNING` / `ERROR`
`DEFAULT_SPACE_NAME`	`Documentation`	新结构的默认空间名称

🔑 获取Wiki.js API密钥

以管理员身份登录您的Wiki.js实例
导航至 行政→ API访问
启用API（如果尚未启用）
点击 新钥匙
给它起个名字（例如。 mcp-server)并将权限设置为 完全访问
立即复制密钥，它不会再次显示

🔍 故障排除

克劳德桌面： `Operation not permitted`

由于macOS Gatekeeper的原因，无法执行shell脚本。直接使用Python二进制文件：

"command": "/path/to/venv/bin/python",
"args": ["/path/to/src/server.py", "--stdio"]

`Read-only file system` 启动时出错

您正在使用相对路径 LOG_FILE 或 WIKIJS_MCP_DB.Claude Desktop从以下位置启动 /.在中使用绝对路径 .env.

`ModuleNotFoundError: No module named 'slugify'`

venv可能是用错误的Python版本创建的。重新创建它：

rm -rf venv
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -c "from slugify import slugify; print('OK')"

页面太大--超出MCP响应大小

使用 wikijs_get_page_metadata 要检查页面大小，请执行以下操作之一：

使用 wikijs_get_page(include_content=False) 仅用于元数据
使用 wikijs_get_page(max_content_chars=500000) 截断
在Wiki.js编辑器中清理嵌入的base64图像（替换为适当的媒体资源）

连接或身份验证错误

验证您的 WIKIJS_URL 没有尾随斜线
确保在Wiki.js管理中启用API
检查API密钥是否具有完全访问权限
跑 wikijs_connection_status 从克劳德那里获取详细状态

📁 项目结构

wiki-js-mcp-server/
├── src/
│   └── server.py              # MCP server — all 24 tools
├── config/
│   └── example.env            # Configuration template
├── Dockerfile                 # python:3.12-slim, non-root user
├── docker-compose.yml         # Pulls hub2rock/wiki-js-mcp-server:latest
├── setup.sh                   # Local setup script (Mac/Linux)
├── start.sh                   # stdio launcher for Claude Desktop
├── requirements.txt           # Python dependencies
├── pyproject.toml             # Package metadata
└── LICENSE                    # MIT

🏢 示例工作流

文档优先开发

在编写任何代码之前，请Claude检查现有的模式：

Search my wiki for authentication patterns before I implement the login feature.

汽车脚手架新项目

Create a complete documentation structure for my project "infra-2rock"
with sections: Overview, Architecture, Networking, Security, Runbooks.

将代码更改同步到文档

I just refactored the Zabbix monitoring module. Sync the change to its wiki page
with this summary: "Migrated alert thresholds to external config file".

项目结束后清理

Delete the entire hierarchy under "old-project" including its root page.

🛠️ 技术栈

FastMCP 3.x --Python MCP SDK
httpx --GraphQL异步HTTP客户端
SQLAlchemy --SQLite ORM文件↔页面映射
Pydantic设置 --环境配置
坚韧 --使用指数回退重试逻辑
优维康 --HTTP模式的ASGI服务器

🤝 贡献

分叉存储库
创建要素分支(git checkout -b feature/my-feature)
提交您的更改(git commit -m 'feat: add my feature')
推到分支(git push origin feature/my-feature)
打开拉取请求

🙏 学分

构建于：

talosdeus/wiki-js-mcp --分层文档工具、文件↔页面同步，SQLite映射数据库
jaalbin24/wikis-mcp-server — move, list, tree 工具、HTTP/SSE传输架构、Docker设置

📄 许可证

麻省理工学院 --免费使用、修改和重新分发，并注明出处。