Wiki.js MCP server

A comprehensive Model Context Protocol (MCP) server for Wiki.js that enables hierarchical documentation management. This server integrates with Cursor IDE to provide intelligent documentation organization and maintenance across multiple repositories.

Quick Start

Environment Setup

First, clone the repository and set up environment variables:

# Copy environment template
cp config/example.env .env

# Edit .env with your credentials:
# - Set POSTGRES_PASSWORD to a secure password
# - Update other settings as needed

Docker Deployment

# Start Wiki.js with Docker
docker-compose -f docker.yml up -d

Wiki.js will be available at http://localhost:3000. Complete the initial setup in the web interface.

Setup MCP Server

# Install Python dependencies
./setup.sh

# Update .env with Wiki.js API credentials:
# - Get API key from Wiki.js admin panel  
# - Set WIKIJS_TOKEN in .env file

# Test the connection
./test-server.sh

# Start MCP server
./start-server.sh

Configure Cursor MCP

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wikijs": {
      "command": "/path/to/wiki-js-mcp/start-server.sh"
    }
  }
}

Enhanced Cursor Integration

Global Rules for Documentation-First Development

Add these Global Rules in Cursor to automatically leverage documentation before coding:

Before writing any code, always:
1. Search existing documentation using wikijs_search_pages to understand current patterns and architecture
2. Check for related components, functions, or modules that might already exist
3. If documentation exists for similar functionality, follow the established patterns and naming conventions
4. If no documentation exists, create it using wikijs_create_page or wikijs_create_nested_page before implementing
5. Always update documentation when making changes using wikijs_sync_file_docs
6. For new features, use wikijs_create_repo_structure to plan the documentation hierarchy first

Usage Tips for Cursor

# Before starting a new feature
"Search the documentation for authentication patterns before implementing login"

# When creating components
"Create nested documentation under frontend-app/components before building the React component"

# For API development
"Check existing API documentation and create endpoint docs using the established structure"

# During refactoring
"Update all related documentation pages for the files I'm about to modify"

Key Features

Hierarchical Documentation

• Repository-level organization for structured docs across multiple repos
• Nested page creation with automatic parent-child relationships
• Auto-organization with smart categorization by file type
• Enterprise scalability to handle hundreds of repos and thousands of files

Core Functionality

• GraphQL API integration with full Wiki.js v2+ compatibility
• File-to-page mapping that automatically links source code and documentation
• Code structure analysis to extract classes, functions, and dependencies
• Bulk operations to update multiple pages simultaneously
• Change tracking to monitor file modifications and sync docs

Docker Setup

• One-command deployment with complete Wiki.js setup with PostgreSQL
• Persistent storage so data survives container restarts
• Health checks with automatic service monitoring
• Production-ready configuration optimized for development and deployment

MCP Tools Overview

Hierarchical Documentation Tools

• wikijs_create_repo_structure - Create complete repository documentation structure
• wikijs_create_nested_page - Create pages with hierarchical paths
• wikijs_get_page_children - Navigate parent-child page relationships
• wikijs_create_documentation_hierarchy - Auto-organize project files into docs

Core Page Management

• wikijs_create_page - Create new pages (with parent support)
• wikijs_update_page - Update existing pages
• wikijs_get_page - Retrieve page content and metadata
• wikijs_search_pages - Search pages by text

Deletion & Cleanup Tools

• wikijs_delete_page - Delete specific pages by ID or path
• wikijs_batch_delete_pages - Batch delete with pattern matching and safety checks
• wikijs_delete_hierarchy - Delete entire page hierarchies with multiple modes
• wikijs_cleanup_orphaned_mappings - Clean up orphaned file-to-page mappings

Organization & Structure Tools

• wikijs_list_spaces - List top-level documentation spaces
• wikijs_create_space - Create new documentation spaces
• wikijs_manage_collections - Manage page collections

File Integration

• wikijs_link_file_to_page - Link source files to documentation pages
• wikijs_sync_file_docs - Sync code changes to documentation
• wikijs_generate_file_overview - Auto-generate file documentation

Usage Examples

Creating Repository Documentation

# Create complete repository structure
await wikijs_create_repo_structure(
    "My Frontend App",
    "Modern React application with TypeScript",
    ["Overview", "Components", "API", "Testing", "Deployment"]
)

# Create nested component documentation
await wikijs_create_nested_page(
    "Button Component",
    "# Button Component\n\nReusable button with multiple variants...",
    "my-frontend-app/components"
)

# Auto-organize entire project
await wikijs_create_documentation_hierarchy(
    "My Project",
    [
        {"file_path": "src/components/Button.tsx"},
        {"file_path": "src/api/users.ts"},
        {"file_path": "src/utils/helpers.ts"}
    ],
    auto_organize=True
)

Documentation Management

# Preview what would be deleted (safe)
preview = await wikijs_delete_hierarchy(
    "old-project",
    delete_mode="include_root",
    confirm_deletion=False
)

# Delete entire deprecated project
await wikijs_delete_hierarchy(
    "old-project",
    delete_mode="include_root", 
    confirm_deletion=True
)

# Batch delete test pages
await wikijs_batch_delete_pages(
    path_pattern="*test*",
    confirm_deletion=True
)

# Clean up orphaned file mappings
await wikijs_cleanup_orphaned_mappings()

Configuration

Environment Variables

# Docker Database Configuration
POSTGRES_DB=wikijs
POSTGRES_USER=wikijs
POSTGRES_PASSWORD=your_secure_password_here

# Wiki.js Connection
WIKIJS_API_URL=http://localhost:3000
WIKIJS_API_KEY=your_jwt_token_here

# Alternative: Username/Password
WIKIJS_USERNAME=your_username
WIKIJS_PASSWORD=your_password

# Database & Logging
WIKIJS_MCP_DB=./wikijs_mappings.db
LOG_LEVEL=INFO
LOG_FILE=wikijs_mcp.log

# Repository Settings
REPOSITORY_ROOT=./
DEFAULT_SPACE_NAME=Documentation

Authentication Options

1. JWT Token (Recommended): Use API key from Wiki.js admin panel
2. Username/Password: Traditional login credentials

Troubleshooting

Docker Issues

# Check containers
docker-compose -f docker.yml ps

# View logs
docker-compose -f docker.yml logs wiki
docker-compose -f docker.yml logs postgres

# Reset everything
docker-compose -f docker.yml down -v
docker-compose -f docker.yml up -d

Connection Issues

# Check Wiki.js is running
curl http://localhost:3000/graphql

# Verify authentication
./test-server.sh

# Debug mode
export LOG_LEVEL=DEBUG
./start-server.sh

Common Problems

• Port conflicts: Change port 3000 in docker.yml if needed
• Database issues: Remove postgres_data/ and restart
• API permissions: Ensure API key has admin privileges
• Python dependencies: Run ./setup.sh to reinstall

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "wikijs" '{"command":"/path/to/wiki-js-mcp/start-server.sh"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "wikijs": {
            "command": "/path/to/wiki-js-mcp/start-server.sh"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "wikijs": {
            "command": "/path/to/wiki-js-mcp/start-server.sh"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect