xwiki-mcp

MCP (Model Context Protocol) server that gives LLM-based agents read and write access to an XWiki instance through the XWiki REST API.

What it does

The server exposes six tools over the MCP stdio transport:

Tool	Description
search_pages	Full-text or title/name/space search across the wiki
get_page	Fetch a page's content, metadata, version, and author by its dot-separated reference
list_spaces	List top-level wiki spaces or subspaces of a given parent
list_pages	List all pages in a space
create_or_update_page	Create a new page or overwrite an existing one (XWiki 2.1 markup)
replace_text	Find-and-replace a text fragment inside a page with ambiguity resolution

Page references

Pages are addressed with dot-separated references matching XWiki's nested space model:

Specs.Billing.WebHome

This maps to the REST path spaces/Specs/spaces/Billing/pages/WebHome.

Search types

search_pages accepts a type parameter with one of:

• content (default) -- full-text search over page bodies
• name -- search by page name
• title -- search by page title
• spaces -- search among space names

Text replacement

replace_text is a safe find-and-replace tool:

• If the target text occurs exactly once, it is replaced automatically.
• If it occurs multiple times, the tool returns all occurrences with surrounding context and asks for a match_number (1-based index) to disambiguate.
• If the text is not found, an error is returned.

This makes it safe for LLM agents to perform targeted edits without accidentally replacing the wrong occurrence.

Requirements

• Python 3.12+
• uv package manager

Quick start with uvx

The fastest way to use xwiki-mcp -- no clone or install needed:

uvx --from git+https://github.com/germanKoch/xwiki-mcp.git xwiki-mcp

This downloads, installs, and runs the server in a temporary environment.

Installation from source

git clone https://github.com/germanKoch/xwiki-mcp.git
cd xwiki-mcp
uv sync

Configuration

The server is configured through environment variables:

Variable	Required	Description
XWIKI_URL	Yes	Base URL of the XWiki instance (e.g. https://wiki.example.com)
XWIKI_USERNAME	No	Username for HTTP Basic authentication
XWIKI_PASSWORD	No	Password for HTTP Basic authentication

If XWIKI_USERNAME and XWIKI_PASSWORD are both set, requests use HTTP Basic Auth. Otherwise, requests are sent without authentication (suitable for public wikis).

Usage

Running directly

export XWIKI_URL="https://wiki.example.com"
export XWIKI_USERNAME="admin"
export XWIKI_PASSWORD="secret"

# If installed from source
python main.py

# Or via the entry point
xwiki-mcp

The server communicates over stdio -- it reads JSON-RPC messages from stdin and writes responses to stdout. This is the standard MCP transport used by Claude Desktop, Claude Code, and other MCP clients.

Claude Desktop configuration

Add this to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "xwiki": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/germanKoch/xwiki-mcp.git", "xwiki-mcp"],
      "env": {
        "XWIKI_URL": "https://wiki.example.com",
        "XWIKI_USERNAME": "admin",
        "XWIKI_PASSWORD": "secret"
      }
    }
  }
}

Claude Code configuration

Add to your Claude Code MCP settings (.claude/settings.json or project-level):

{
  "mcpServers": {
    "xwiki": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/germanKoch/xwiki-mcp.git", "xwiki-mcp"],
      "env": {
        "XWIKI_URL": "https://wiki.example.com",
        "XWIKI_USERNAME": "admin",
        "XWIKI_PASSWORD": "secret"
      }
    }
  }
}

Project structure

xwiki-mcp/
  xwiki_mcp/
    __init__.py
    server.py      -- MCP server, all tools defined here
  main.py          -- convenience entry point
  pyproject.toml   -- project metadata, dependencies, and entry point
  uv.lock          -- locked dependency versions
  CLAUDE.md        -- instructions for Claude Code
  .python-version  -- pinned Python version (3.12)

Dependencies

• mcp[cli] -- Model Context Protocol SDK for Python
• httpx -- async HTTP client for XWiki REST API calls

License

Not yet specified.