mediawiki-api-mcp

MediaWiki API MCP Server

A Model Context Protocol (MCP) server that allows LLMs to interact with MediaWiki installations through the MediaWiki API as a bot user.

Features

Tools

The server provides various MCP tools with the wiki_ prefix:

Installation

1. Clone the repository and checkout the main branch

2. Install dependencies using UV:

uv install

3. Set up environment variables:

export MEDIAWIKI_API_URL="http://mediawiki.test/api.php"
export MEDIAWIKI_API_BOT_USERNAME="YourUserName@YourBotName"
export MEDIAWIKI_API_BOT_PASSWORD="YourBotPassword"
export MEDIAWIKI_API_BOT_USER_AGENT="MediaWiki-MCP-Bot/1.0 (your.email@mediawiki.test)"  # Optional

Usage

Running the Server

uv run mediawiki-api-mcp

Or directly:

python -m mediawiki_api_mcp.server

Configuration with Claude Desktop

Configuration File Location

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

Template Configuration

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "mediawiki-api": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mediawiki-api-mcp",
        "run",
        "mediawiki-api-mcp"
      ],
      "env": {
        "MEDIAWIKI_API_URL": "http://mediawiki.test/api.php",
        "MEDIAWIKI_API_BOT_USERNAME": "YourUserName@YourBotName",
        "MEDIAWIKI_API_BOT_PASSWORD": "YourBotPassword",
        "MEDIAWIKI_API_BOT_USER_AGENT": "MediaWiki-MCP-Bot/1.0 (your.email@mediawiki.test)"
      }
    }
  }
}

Configuration Instructions

1. Replace /absolute/path/to/mediawiki-api-mcp with the actual absolute path to this project directory
2. Update MEDIAWIKI_API_URL with your MediaWiki installation's API endpoint
3. Set MEDIAWIKI_API_BOT_USERNAME to your bot username (typically in format YourUserName@YourBotName)
4. Set MEDIAWIKI_API_BOT_PASSWORD to the generated bot password from your wiki's Special:BotPasswords page
5. Customize MEDIAWIKI_API_BOT_USER_AGENT with appropriate contact information (optional)

Bot Password Setup

Create bot credentials at e.g.: http://mediawiki.test/index.php/Special:BotPasswords

Required permissions:

• Basic rights: Read pages
• High-volume editing: Edit existing pages, Create, edit, and move pages
• Additional permissions as needed for your specific use case

Security Notes

• Keep your bot credentials secure and never commit them to version control
• Use the principle of least privilege when setting bot permissions
• Monitor bot activity through your MediaWiki's logging interface
• Consider using IP restrictions for additional security

Development

Technology Stack

• MCP SDK: mcp >= 1.2.0 (using FastMCP pattern)
• HTTP Client: httpx >= 0.27.0 for MediaWiki API calls
• Data Validation: pydantic >= 2.0.0 for configuration models
• Environment: python-dotenv >= 1.0.0 for configuration
• Testing: pytest with pytest-asyncio for async testing
• Code Quality: ruff for linting, mypy for type checking

Architecture

• FastMCP server with @mcp.tool() decorators
• Separation of concerns: server → handler → client → MediaWiki API
• AsyncIO throughout for non-blocking operations
• Environment-based configuration for MediaWiki credentials

Client Layer (client.py and client_modules/)

• Handles MediaWiki API authentication and requests
• Manages CSRF tokens and session state
• Provides typed methods for API operations

Tools Layer (tools/)

• Defines MCP tool schemas using JSON Schema
• Separated by functional area (edit, search)
• Ensures all tools have wiki_ prefix

Handlers Layer (handlers/)

• Implements actual tool logic
• Handles argument validation and error handling
• Returns properly formatted MCP responses

Server Layer (server.py and server_tools/)

• Main MCP server orchestration
• Routes tool calls to appropriate handlers
• Manages configuration and client lifecycle

Project Structure

The project is organized into modular components for maintainability:

mediawiki-api-mcp/
├── mediawiki_api_mcp/
│   ├── __init__.py
│   ├── server.py             # FastMCP server with tool definitions
│   ├── client.py             # MediaWiki API client
│   ├── client_modules/       # Client modules for API operations
│   │    ├── __init__.py      # Client module exports
│   │    └── client_*.py        # Individual client modules
│   ├── handlers/             # Business logic handlers
│   │    ├── __init__.py      # Handler exports
│   │    └── wiki_*.py        # Individual tool handlers
│   ├── tools/                # Tool schemas
│   │   ├── __init__.py       # Tool schema exports
│   │   └── wiki_*.py         # Individual tool schemas
│   └── server_tools/         # Tool definitions
│       ├── __init__.py       # Tool definition exports
│       └── wiki_*.py         # Individual tool definitions
├── tests/                    # Test suite
│   └── test_*.py             # Test files matching handlers
├── docs/                     # Documentation
│   └── tools/                # Tool-specific documentation
│       └── wiki_*.md         # Individual tool docs
├── pyproject.toml            # Project configuration
└── uv.lock                   # Dependency lock file

Running Tests

uv run pytest

Run specific test modules, e.g.:

uv run pytest tests/test_server.py
uv run pytest tests/test_tools.py
uv run pytest tests/test_wiki_page_edit.py
uv run pytest tests/test_wiki_search.py
uv run pytest tests/test_wiki_opensearch.py

Code Quality

# Linting
uv run ruff check

# Type checking
uv run mypy mediawiki_api_mcp

Error Handling

The server implements comprehensive error handling:

• Configuration errors: Missing environment variables
• Authentication errors: Invalid credentials or permissions
• API errors: Network issues, invalid requests
• Tool errors: Missing parameters, invalid arguments

All errors are returned as MCP TextContent responses for LLM visibility.

Security

• Bot credentials are required for editing operations
• All API requests include proper User-Agent headers
• CSRF tokens are automatically managed
• Input validation on all tool parameters

License

MIT License