wikijs-mcp

This project is an English fork/adaptation of https://github.com/talosdeus/wiki-js-mcp.Original project licensed under the MIT License.

Wiki.js MCP Server

MCP License Node.js

Model Context Protocol (MCP) server for Wiki.js integration via GraphQL API.

📖 Description

This project provides an MCP server for interacting with Wiki.js through GraphQL API. MCP (Model Context Protocol) is an open protocol developed by Anthropic that enables AI models to safely interact with external services and tools.

The server provides a unified interface for working with Wiki.js that can be used by various AI agents and tools supporting MCP.

✨ Features

📄 Page Management

Get Wiki.js pages by ID
Get page content by ID
List pages with sorting options
Search pages by query
Create new pages
Update existing pages
Delete pages
🆕 List all pages including unpublished
🆕 Search unpublished pages
🆕 Force delete pages (including unpublished)
🆕 Get page publication status
🆕 Publish unpublished pages

👥 User Management

List users
Search users by query
Create new users
Update user information

🔧 Group Management

List user groups

✍️ Blogging Tools

Fetch versioned blog-writing prompts from Wiki.js
Create unpublished blog drafts under a dedicated drafts path
Generate draft slugs automatically from titles
Support custom draft descriptions and tags

🌐 Transports

STDIO: for editor integration (Cursor, VS Code)
HTTP: for web integrations and API access

🚀 Quick Start

⚡ Want to start right now? See 5-Minute Guide

Installation

Clone the repository:

git clone https://github.com/heAdz0r/wikijs-mcp-server.git
cd wikijs-mcp-server

Run automatic setup:

npm run setup

This script will automatically:

Install dependencies
Create .env file based on example.env
Build TypeScript code

Configuration

Edit the .env file and specify your Wiki.js settings:

# Port for HTTP MCP server
PORT=3200

# Base URL for Wiki.js (without /graphql)
WIKIJS_BASE_URL=http://localhost:3000

# Wiki.js API token
WIKIJS_TOKEN=your_wikijs_api_token_here

# Optional blog workflow paths
WIKIJS_BLOG_PROMPT_PATH=blogs/_prompt/versions
WIKIJS_BLOG_DRAFTS_PATH=blogs/drafts

Edit the .cursor/mcp.json file and replace your_wikijs_api_token_here with your real token

How to get Wiki.js API token:

Log into Wiki.js admin panel

Go to "API" section

Create a new API key with necessary permissions

Copy the token to .env AND to .cursor/mcp.json

📦 Running

HTTP server (recommended)

# Start main HTTP server with Cursor MCP support
npm start
# or
npm run start:http

# Stop server
npm run stop

TypeScript version

npm run start:typescript

STDIO mode (for direct editor integration)

npm run server:stdio

Development mode

npm run dev

Testing

npm test

🔌 Editor Integration

Cursor IDE

⚠️ IMPORTANT: Without .cursor/mcp.json file, Cursor integration will NOT work!

Quick Setup

Start HTTP server:

npm start

Automatic configuration setup:

npm run setup:cursor

Edit .cursor/mcp.json and specify your real token:

{
  "mcpServers": {
    "wikijs": {
      "transport": "http",
      "url": "http://localhost:3200/mcp",
      "events": "http://localhost:3200/mcp/events",
      "cwd": ".",
      "env": {
        "WIKIJS_BASE_URL": "http://localhost:3000",
        "WIKIJS_TOKEN": "your_real_wiki_js_token_here"
      }
    }
  }
}

Critical Parameters

transport: "http" - mandatory HTTP transport
url: "http://localhost:3200/mcp" - exact URL for JSON-RPC
events: "http://localhost:3200/mcp/events" - URL for Server-Sent Events
WIKIJS_TOKEN - real Wiki.js API token (not placeholder!)

Verification

After setup, tools with mcp_wikijs_* prefix should appear in Cursor:

mcp_wikijs_list_pages()
mcp_wikijs_search_pages()
mcp_wikijs_get_page()
And others...

VS Code (with MCP extension)

Add to VS Code settings:

{
  "mcp.servers": {
    "wikijs": {
      "command": "node",
      "args": ["lib/mcp_wikijs_stdin.js"],
      "cwd": "/path/to/wikijs-mcp"
    }
  }
}

🛠 Development

Project Structure

wikijs-mcp-server/
├── src/                    # TypeScript source code
│   ├── server.ts          # HTTP server
│   ├── tools.ts           # Tool definitions
│   ├── api.ts             # Wiki.js API client
│   ├── types.ts           # Data types
│   ├── schemas.ts         # Zod validation schemas
│   └── README.md          # Source code documentation
├── lib/                   # JavaScript library files
│   ├── fixed_mcp_http_server.js    # Main HTTP server (compiled)
│   ├── mcp_wikijs_stdin.js         # STDIN server for editors
│   ├── mcp_client.js               # Demo MCP client
│   ├── mcp_wrapper.js              # MCP protocol utilities
│   └── README.md                   # Library documentation
├── scripts/               # Management scripts
│   ├── setup.sh          # Initial setup
│   ├── start_http.sh     # Start HTTP server
│   ├── stop_server.sh    # Stop HTTP server
│   ├── start_typescript.sh # Start TypeScript version
│   ├── setup_cursor_mcp.sh # Cursor setup
│   ├── test.sh           # Run tests
│   ├── test_mcp.js       # Test HTTP server
│   ├── test_mcp_stdin.js # Test STDIN server
│   └── README.md         # Scripts documentation
├── .cursor/               # Cursor MCP configuration
│   └── mcp.json          # MCP configuration file (CRITICALLY IMPORTANT!)
├── dist/                  # Compiled TypeScript code
├── package.json           # Project metadata
└── README.md             # Main documentation

🚨 CRITICALLY IMPORTANT: .cursor/mcp.json file is required for Cursor integration!

Available Scripts

Setup and Build

npm run setup - Initial project setup
npm run build - Build TypeScript project
npm run setup:cursor - Setup Cursor integration

Running Servers

npm start / npm run start:http - HTTP MCP server (port 3200)
npm run stop - Stop all MCP servers
npm run start:typescript - TypeScript version of server (port 8000)
npm run server:stdio - STDIO version for direct integration

Development and Testing

npm run dev - Development mode with hot reload
npm run demo - Capability demonstration
npm test - Run tests
npm run client - Run demo client

API Endpoints (HTTP mode)

GET /tools - List of available tools
GET /health - Server health check
POST /mcp - MCP JSON-RPC endpoint

Usage Examples

// Get list of pages
{
  "method": "list_pages",
  "params": {
    "limit": 10,
    "orderBy": "TITLE"
  }
}

// Create new page
{
  "method": "create_page",
  "params": {
    "title": "New Page",
    "content": "# Title\n\nContent...",
    "path": "folder/new-page"
  }
}

### Search for pages:
```python
# Search in all content and metadata
result = await mcp_client.call_tool("search_pages", {
    "query": "magic system",
    "limit": 5
})

Working with Unpublished Pages:

# Get all pages including unpublished ones
all_pages = await mcp_client.call_tool("list_all_pages", {
    "limit": 100,
    "includeUnpublished": True
})

# Search only unpublished pages
unpublished = await mcp_client.call_tool("search_unpublished_pages", {
    "query": "draft",
    "limit": 10
})

# Check page publication status
status = await mcp_client.call_tool("get_page_status", {
    "id": 42
})

# Publish an unpublished page
result = await mcp_client.call_tool("publish_page", {
    "id": 42
})

# Force delete page (works with unpublished pages)
result = await mcp_client.call_tool("force_delete_page", {
    "id": 42
})

Blogging workflow:

# List available blog prompt versions
versions = await mcp_client.call_tool("get_blog_prompt", {})

# Fetch a specific prompt template
prompt = await mcp_client.call_tool("get_blog_prompt", {
    "version": "v1"
})

# After writing content from the prompt guidance, save it as an unpublished draft
draft = await mcp_client.call_tool("create_blog_draft", {
    "title": "Building Better Wiki.js Documentation",
    "content": "# Building Better Wiki.js Documentation\n\nDraft content...",
    "slug": "building-better-wikijs-documentation",
    "description": "A draft post about improving Wiki.js documentation workflows.",
    "tags": ["blog", "draft", "wikijs"]
})

User management:

# List all users
users = await mcp_client.call_tool("list_users")

# Search users by query
search_result = await mcp_client.call_tool("search_users", {
    "query": "John"
})

# Create new user
new_user = await mcp_client.call_tool("create_user", {
    "email": "[email protected]",
    "name": "John Doe",
    "passwordRaw": "password123",
    "providerKey": "local",
    "groups": [1],
    "mustChangePassword": false,
    "sendWelcomeEmail": true
})

# Update user information
updated_user = await mcp_client.call_tool("update_user", {
    "id": 1,
    "name": "John Doe Updated"
})

🐛 Troubleshooting

Connection Issues

Ensure Wiki.js is running and accessible
Check WIKIJS_BASE_URL correctness
Verify API token is valid

MCP Issues

Check Node.js version (requires >=18.0.0)
Ensure all dependencies are installed
Check server logs for errors

📚 Documentation

Source Code Documentation - TypeScript source code structure
Library Documentation - JavaScript library files
Scripts Documentation - description of all management scripts
Changelog - release and update log
License - project usage terms

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is distributed under the MIT License. See LICENSE file for details.

🔗 Useful Links

Wiki.js - Official Wiki.js website
Model Context Protocol - MCP specification
Anthropic - MCP protocol developer
GraphQL - Query language for APIs

⭐ Support

If this project helped you, please give it a ⭐ on GitHub!

Have questions? Create an Issue or refer to the documentation.

🆕 New Feature: Automatic URLs

Search Stages

Search works in 4 stages:

GraphQL API search - fast search through indexed content
Metadata search - search in titles, paths, and page descriptions
HTTP content search - deep search in page content via HTTP
Forced verification - fallback search on known pages

Usage Examples

Content Search

{
  "method": "search_pages",
  "params": {
    "query": "ZELEBOBA",
    "limit": 5
  }
}

Result:

[
  {
    "id": 103,
    "path": "test/test-page",
    "title": "Test Page",
    "description": "Test page to demonstrate Wiki.js API capabilities",
    "url": "http://localhost:8080/en/test/test-page"
  }
]

Title Search

{
  "method": "search_pages",
  "params": {
    "query": "find me",
    "limit": 3
  }
}

Result:

[
  {
    "id": 108,
    "path": "test/test-gemini-mcp",
    "title": "Test Gemini MCP Page (find me)",
    "url": "http://localhost:8080/en/test/test-gemini-mcp"
  }
]

New Search Benefits

✅ Finds pages even with limited API permissions - uses HTTP fallback
✅ Multi-level search - combines multiple strategies
✅ Content search - finds text inside pages
✅ Metadata search - titles, paths, descriptions
✅ Fallback methods - guaranteed results for known pages
✅ Correct URLs - all results contain ready-to-use links

Technical Details

HTML Content Processing

The system automatically extracts text from HTML using:

Search in <template slot="contents"> block
HTML tags and entities cleanup
Fallback to full page content

With limited GraphQL API permissions, the system:

Switches to HTTP method for content retrieval
Uses direct requests to HTML pages
Preserves all page metadata

📝 Changelog

Version 1.3.0 - Unpublished Pages Management (Latest)

🆕 New Features:

list_all_pages - Get all pages including unpublished ones
search_unpublished_pages - Search specifically in unpublished pages
force_delete_page - Enhanced deletion that works with unpublished pages
get_page_status - Check publication status of any page
publish_page - Publish unpublished pages programmatically
get_blog_prompt - Fetch versioned blog-writing prompts from Wiki.js
create_blog_draft - Create unpublished blog drafts for review

🔧 Improvements:

Enhanced server API with new routes for unpublished page management
Better error handling for page deletion operations
Comprehensive GraphQL mutation support for advanced page operations
Restructured project: Moved JavaScript files to lib/ directory for better organization
Blog workflow paths can be configured with WIKIJS_BLOG_PROMPT_PATH and WIKIJS_BLOG_DRAFTS_PATH

🐛 Bug Fixes:

Fixed issues with accessing unpublished pages through standard APIs
Improved authentication handling for admin-level operations

Version 1.2.0 - International Release

🌍 Internationalization:

Complete English translation of documentation
README.md and QUICK_START.md now available in English
Prepared for international market expansion

Version 1.1.0 - Enhanced Search & User Management

✨ Features:

Smart multi-method page search (GraphQL + content + metadata)
User management tools (create, update, search)
Group management capabilities
Improved content extraction from HTML pages

🛠️ Available Tools

📄 Page Tools

Tool Name	Description	Parameters
`get_page`	Get page information by ID	`id: number`
`get_page_content`	Get page content by ID	`id: number`
`list_pages`	List pages with sorting	`limit?: number, orderBy?: string`
`search_pages`	Search pages by query	`query: string, limit?: number`
`create_page`	Create new page	`title: string, content: string, path: string, description?: string, tags?: string[]`
`update_page`	Update existing page	`id: number, content: string`
`delete_page`	Delete page	`id: number`
`list_all_pages`	🆕 List all pages including unpublished	`limit?: number, orderBy?: string, includeUnpublished?: boolean`
`search_unpublished_pages`	🆕 Search only unpublished pages	`query: string, limit?: number`
`force_delete_page`	🆕 Force delete page (works with unpublished)	`id: number`
`get_page_status`	🆕 Get page publication status	`id: number`
`publish_page`	🆕 Publish unpublished page	`id: number`

✍️ Blogging Tools

Tool Name	Description	Parameters
`get_blog_prompt`	Fetch a blog prompt version or list versions	`version?: string`
`create_blog_draft`	Create an unpublished blog draft under drafts	`title: string, content: string, slug?: string, description?: string, tags?: string[]`

👥 User Tools

Tool Name	Description	Parameters
`list_users`	List all users	None
`search_users`	Search users by query	`query: string`
`create_user`	Create new user	`email: string, name: string, passwordRaw: string, providerKey?: string, groups?: number[], mustChangePassword?: boolean, sendWelcomeEmail?: boolean`
`update_user`	Update user information	`id: number, name: string`

🔗 Group Tools

Tool Name	Description	Parameters
`list_groups`	List user groups	None

wikijs-mcp

Wiki.js MCP Server

📖 Description

✨ Features

📄 Page Management

👥 User Management

🔧 Group Management

✍️ Blogging Tools

🌐 Transports

🚀 Quick Start

Installation

Configuration

📦 Running

HTTP server (recommended)

TypeScript version

STDIO mode (for direct editor integration)

Development mode

Testing

🔌 Editor Integration

Cursor IDE

Quick Setup

Critical Parameters

Verification

VS Code (with MCP extension)

🛠 Development

Project Structure

Available Scripts

Setup and Build

Running Servers

Development and Testing

API Endpoints (HTTP mode)

Usage Examples

Working with Unpublished Pages:

Blogging workflow:

User management:

🐛 Troubleshooting

Connection Issues

MCP Issues

📚 Documentation

🤝 Contributing

📄 License

🔗 Useful Links

⭐ Support

🆕 New Feature: Automatic URLs

Search Stages

Usage Examples

Content Search

Title Search

New Search Benefits

Technical Details

HTML Content Processing

📝 Changelog

Version 1.3.0 - Unpublished Pages Management (Latest)

🆕 New Features:

🔧 Improvements:

🐛 Bug Fixes:

Version 1.2.0 - International Release

🌍 Internationalization:

Version 1.1.0 - Enhanced Search & User Management

✨ Features:

🛠️ Available Tools

📄 Page Tools

✍️ Blogging Tools

👥 User Tools

🔗 Group Tools

MCP Server · Populars

MCP Server · New