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:
| Tool | Description |
|---|---|
wiki_page_edit | Edit or create MediaWiki pages with comprehensive editing options |
wiki_page_get | Retrieve page information and content |
wiki_page_parse | Parse page content with support for wikitext processing, HTML generation, metadata extraction, and advanced parsing features |
wiki_page_compare | Compare two pages, revisions, or text content to show differences between them |
wiki_page_move | Move pages with support for talk pages, subpages, and redirects |
wiki_page_delete | Delete pages with support for talk pages, watchlist management, and logging |
wiki_page_undelete | Undelete (restore) deleted MediaWiki pages with comprehensive restoration options |
wiki_search | Search for pages using MediaWiki's search API with advanced filtering |
wiki_opensearch | Search using OpenSearch protocol for quick suggestions and autocomplete |
wiki_meta_siteinfo | Get overall site information including general info, namespaces, statistics, extensions, and more |
Installation
-
Clone the repository and checkout the
mainbranch -
Install dependencies using UV:
uv install
- 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
- Replace
/absolute/path/to/mediawiki-api-mcpwith the actual absolute path to this project directory - Update
MEDIAWIKI_API_URLwith your MediaWiki installation's API endpoint - Set
MEDIAWIKI_API_BOT_USERNAMEto your bot username (typically in formatYourUserName@YourBotName) - Set
MEDIAWIKI_API_BOT_PASSWORDto the generated bot password from your wiki'sSpecial:BotPasswordspage - Customize
MEDIAWIKI_API_BOT_USER_AGENTwith 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