Summary
A path traversal vulnerability in douinc mkdocs-mcp-plugin (up to 0.4.1) allows attackers to manipulate the docs_dir/file_path parameters in the server's read_document and list_documents functions to access files outside the intended documentation directory.
When exposed over a network, this can enable remote attackers to read arbitrary files that the server process can access, including sensitive configuration or source files, depending on deployment.
Affected context
The issue arises in deployments using the mkdocs-mcp-plugin's built-in server functionality where:
- The
server.pyendpoint exposingread_documentand/orlist_documentsis reachable over a network interface. - User-controlled input is used to derive
docs_dirorfile_pathvalues. - The server process has filesystem access to directories containing sensitive files.
In such setups, the absence of strict path normalization and allowed-root validation can allow navigation outside the intended documentation directory.
Exploit preconditions
- Attack surface: HTTP or RPC endpoints provided by the plugin's server that accept
docs_dirand/orfile_pathparameters. - Required access: Network access to the documentation server (e.g., internal or Internet-facing) with the ability to send crafted requests.
- Trigger point: Invocation of
read_documentorlist_documentswhere the server concatenates or otherwise uses attacker-controlled path components. - Why exploitation is possible: The implementation does not reliably canonicalize and constrain the resulting path to a fixed, trusted root directory, so sequences like
../or absolute paths can escape the intended docs directory.
Why this happens
This vulnerability stems from improper restriction of filesystem paths derived from user input, matching CWE-22: Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
The server trusts docs_dir and/or file_path values without robust canonicalization and boundary checks, likely joining them directly to construct filesystem paths and then reading or listing content.
Without validating that the resolved, absolute path remains within an approved root (such as the documentation directory), attackers can use traversal tokens or absolute paths to target arbitrary files accessible to the server process.
Potential impact
- Reading arbitrary files that the mkdocs-mcp-plugin server process can access, including application configuration, environment files, or API keys.
- Exposure of source code, templates, or internal documentation not meant for public consumption.
- Information disclosure that may aid in chaining with other vulnerabilities (e.g., locating credentials, internal network configuration, or framework secrets).
- In some deployment configurations, potential access to log files containing user data, tokens, or session identifiers.
General mitigation guidance
Effective mitigation focuses on strictly constraining and validating all filesystem paths derived from user input:
- Resolve user-supplied paths (e.g., via
realpath-style APIs) and verify that the canonical path remains under an expected documentation root directory. - Maintain a configured, fixed documentation root on the server, and avoid letting clients control base directories like
docs_dir. - Normalize input to remove or reject path traversal sequences such as
../, absolute paths, or symbolic link abuse, rather than blindly concatenating segments. - Implement a whitelist-based approach for accessible documentation paths, or use a virtual file mapping instead of exposing the raw filesystem structure.
- Run the documentation server with least-privilege filesystem permissions so that even if traversal occurs, exposure is limited to non-sensitive files.
How teams detect issues like this
Detection commonly relies on a combination of code-level and behavioral monitoring:
- Static analysis: Configure rules that flag direct use of user input in file path construction, especially when combined with functions like
open,os.path.join,listdir, or similar file-access APIs without canonicalization and root checks. - Code review: During manual review, look for server handlers that use request parameters like
file_pathordocs_dirto construct filesystem paths; verify that absolute path resolution and root enforcement are present. - Security testing: Include automated tests or DAST scanners that attempt directory traversal payloads (e.g.,
../, nested traversal, encoded traversal) against endpoints serving documentation or static files. - Runtime monitoring: Inspect server logs for repeated access attempts using traversal patterns (e.g.,
../,%2e%2e/), which may indicate exploitation or probing.

