Pmwiki MCP

🚀 PmWiki MCP Server

The MCP (Model Context Protocol) server enables seamless interaction between an LLM and PmWiki.

Version française / French version

🚀 Quick Start

With Docker Compose (Docker Hub image)

The simplest way is to use the published image from Docker Hub:

docker compose up -d

With Docker Compose (local build)

If you prefer to build the image locally:

1. Edit docker-compose.yml, comment out the image: line, and uncomment the build: . line.
2. Run the following command:

docker compose up -d --build

Direct Docker Usage

Without docker-compose, you can run the server directly:

docker run -d \
  --name pmwiki-mcp-server \
  -p 3000:3000 \
  -v /path/to/your/wiki.d:/wiki_data:ro \
  -e WIKI_DIR=/wiki_data \
  kcofoni/pmwiki-mcp:latest

The server will be accessible at http://localhost:3000 (or http://vmtest:3000 from other machines on the network).

Verification

# Check that the server is running
docker logs pmwiki-mcp-server

# Test the SSE connection
curl -N http://localhost:3000/sse

✨ Features

Architecture

The server employs the MCP protocol with SSE (Server-Sent Events) transport to allow an LLM to interact with your PmWiki instance.

Endpoints

• GET /sse: Establishes a bidirectional communication SSE connection.
• POST /messages/: Receives messages from the MCP client.

Available Features

Once connected, your LLM can access the following:

Resources

All wiki pages are available as resources with the URI pmwiki://Group.PageName.

Tools

1. search_wiki: Searches for text across all pages.
   • Parameters:
     • query (required): The text to search for.
     • case_sensitive (optional): Enables case-sensitive search (default: false).
2. read_page: Reads the complete content of a page.
   • Parameters:
     • page_name (required): The page name (e.g., Main.HomePage or Main/HomePage).
3. list_pages: Lists all wiki pages.
   • Parameters:
     • group (optional): Filters pages by group.

📦 Installation

Wiki Directory Mount

The PmWiki directory is mounted from the host machine to the Docker container:

volumes:
  - /home/docker/appdata/html/wiki.d:/wiki_data:ro

⚠️ Important Note

• /home/docker/appdata/html/wiki.d is the path on the host machine - adjust it according to your actual situation.
• Replace this path with the actual path to your PmWiki wiki.d directory.
• The volume is mounted read-only (:ro) for security reasons.
• /wiki_data is the internal container path and should not be modified.

Docker Hub

The image is publicly available on Docker Hub:

• Repository: kcofoni/pmwiki-mcp
• Latest tag: kcofoni/pmwiki-mcp:latest
• Stable version: kcofoni/pmwiki-mcp:v1.0.2

To pull the latest version:

docker pull kcofoni/pmwiki-mcp:latest

To pull a specific version:

docker pull kcofoni/pmwiki-mcp:v1.0.2

💻 Usage Examples

Client Configuration - Claude Desktop

Add the following configuration to your Claude Desktop configuration file: On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pmwiki": {
      "command": "mcp-proxy",
      "args": [
        "--transport=sse",
        "http://vmtest:3000/sse"
      ]
    }
  }
}

⚠️ Important Note

• vmtest is the hostname of the machine hosting the MCP server Docker container.
• Replace vmtest with:
  • localhost if Claude Desktop runs on the same machine as the server.
  • The hostname or IP address of the machine running the Docker container (e.g., 192.168.1.100:3000/sse).
• The mcp-proxy tool must be installed (usually provided with Claude Desktop).
• The proxy manages the SSE connection between Claude Desktop and the MCP server.

📚 Documentation

Technical Architecture

• Language: Python 3.11
• Web Framework: Starlette + Uvicorn
• Protocol: MCP over SSE
• Page Format: PmWiki (files in wiki.d/)

Logs

# View logs in real-time
docker logs -f pmwiki-mcp-server

# Last 50 lines
docker logs --tail 50 pmwiki-mcp-server

Troubleshooting

Server won't start

Check if the wiki directory exists:

ls -la /home/docker/appdata/html/wiki.d

404 error on a page

Use the list_pages tool to view all available pages. Ensure you use the exact PmWiki filename format (e.g., Main.HomePage instead of Main/HomePage).

SSE connection fails

Check if port 3000 is properly exposed:

docker ps | grep pmwiki-mcp-server

Development

File Structure

pmwiki-mcp/
├── pmwiki_mcp_server.py    # MCP server
├── requirements.txt         # Python dependencies
├── Dockerfile              # Docker image
├── docker-compose.yml      # Docker Compose configuration
├── README.md              # This documentation (English)
└── README_fr.md           # French documentation

Code Modification

After modifying the code, run:

docker compose up -d --build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.