Wiki Js MCP Server

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密钥)

1.克隆和设置

git clone https://github.com/hub2rock/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个）

🔧 连接

📝 核心页面管理

🏗️ 分层文档

🗂️ 空间与组织

🗑️ 删除和清理

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

______________________________________________________________________

📄 处理大页面

带有嵌入式图像（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/hub2rock/wiki-js-mcp-server/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/hub2rock/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值：

echo -n "user:password" | base64

______________________________________________________________________

⚙️ 环境变量

______________________________________________________________________

🔑 获取Wiki.js API密钥

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

______________________________________________________________________

🔍 故障排除

克劳德桌面： 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服务器

______________________________________________________________________

🤝 贡献

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

______________________________________________________________________

🙏 学分

构建于：

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

______________________________________________________________________

📄 许可证

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