Man MCP Server

What is Man MCP Server about?

Man MCP Server exposes the standard Linux man page system as MCP resources. It lets callers query keywords, list man‑page sections, and fetch full page contents through man:// URIs, delivering clean, AI‑friendly text.

How to use Man MCP Server?

1. Installation
   • Clone the repository and install dependencies with either uv sync (recommended) or pip install ..
2. Running the server
   • Execute uv run python3 man_server.py or python3 man_server.py.
   • For VS Code integration, add a .vscode/mcp.json configuration pointing to the script (see README for examples).
3. Calling the service
   • Use the provided Python tools (search_man_pages, get_man_page, list_man_sections) or request MCP resources such as man://search/network or man://1/ls.

Key features of Man MCP Server

• Keyword search of man pages via apropos with async timeout protection.
• Retrieval of full man page content by name and optional section.
• Listing of all man‑page sections (1‑9) with descriptions.
• Cleaned and formatted output, stripping ANSI codes for AI consumption.
• Fully asynchronous API with configurable timeouts and fallback mechanisms.
• MCP resource exposure using man:// URIs for seamless integration with MCP‑compatible tools.

Use cases of Man MCP Server

• AI assistants that need to answer command‑line questions with authoritative documentation.
• IDE extensions (e.g., VS Code) providing on‑demand man‑page lookup without leaving the editor.
• Automated scripts that validate command usage or generate documentation snippets.
• Educational tools teaching Linux commands by retrieving exact man‑page excerpts.

FAQ from the Man MCP Server

Q: Which operating systems are supported? A: Linux systems with the standard man and apropos commands installed.

Q: What Python version is required? A: Python 3.10 or newer.

Q: How does the server handle missing pages? A: It returns a clear error message indicating that the requested page or section could not be found.

Q: Can I customize the timeout for subprocess calls? A: Yes, the timeout value is configurable in the service code.

Q: Is there a way to run the server without uv? A: Absolutely; the server can be started with python3 man_server.py after installing dependencies via pip.

MCP Man Pages Server

A Model Context Protocol (MCP) server that provides access to Linux man pages using FastMCP. This server allows AI assistants to search, retrieve, and explore system documentation directly from your local machine.

Features

• Search man pages: Find documentation by keyword or command name using apropos
• Retrieve specific pages: Get complete man page content by name and optional section
• List sections: Browse available man page sections (1-9) with descriptions
• Clean formatting: Man page content is cleaned and formatted for AI consumption
• Async operations: All operations are asynchronous with timeout protection
• MCP Resources: Expose man pages as resources with man:// URIs

Installation

Using uv (recommended)

# Clone the repository
git clone https://github.com/guyru/man-mcp-server.git
cd man-mcp-server

# Install dependencies
uv sync

# Install with development tools
uv sync --extra dev

Using pip

# Clone the repository
git clone https://github.com/guyru/man-mcp-server.git
cd man-mcp-server

# Install the package and dependencies from pyproject.toml
pip install .

# Or install in development mode (editable install)
pip install -e .

# For development with optional dependencies
pip install -e .[dev]

Usage

Running the Server

# Using uv
uv run python3 man_server.py

# Using python directly
python3 man_server.py

# With MCP development tools
uv run mcp dev man_server.py

VS Code Integration

To integrate this MCP server with VS Code, you need to create a configuration file:

1. Create the VS Code MCP configuration directory (if it doesn't exist):

   mkdir -p .vscode
   

2. Create .vscode/mcp.json with the following content:

   {
     "servers": {
       "man-mcp-server": {
         "type": "stdio",
         "command": "uv",
         "args": ["run", "--directory", "/path/to/man-mcp-server", "python3", "man_server.py"]
       }
     }
   }
   

3. Update the path in the configuration above to match your actual project directory.

4. Alternative configuration if you're not using uv:

   {
     "servers": {
       "man-mcp-server": {
         "type": "stdio",
         "command": "python3",
         "args": ["/path/to/man-mcp-server/man_server.py"]
       }
     }
   }
   

This configuration allows MCP-compatible VS Code extensions to communicate with your man pages server.

Available Tools

1. search_man_pages

Search for man pages by keyword or topic:

search_man_pages("permission")  # Find pages about permissions
search_man_pages("network")     # Find networking-related pages

2. get_man_page

Retrieve the full content of a specific man page:

get_man_page("ls")           # Get ls man page (any section)
get_man_page("chmod", "1")   # Get chmod from section 1 specifically
get_man_page("printf", "3")  # Get printf from section 3 (C library)

3. list_man_sections

List all available man page sections with descriptions:

list_man_sections()  # Shows sections 1-9 with descriptions

Available Resources

The server exposes man pages as resources using man:// URIs:

• man://sections - List of all available sections
• man://search/{keyword} - Search results for a keyword
• man://{section}/{page} - Specific man page content

Examples:

• man://search/network - Search results for "network"
• man://1/ls - The ls command man page from section 1
• man://3/printf - The printf function man page from section 3

Requirements

• Operating System: Linux with standard man page system
• Python: 3.10 or higher
• Commands: man, apropos (usually pre-installed)
• Dependencies: mcp library

Development

Testing the Server

# Test search functionality
uv run python3 -c "
from man_server import man_service
import asyncio
print(asyncio.run(man_service.search_man_pages('ls')))
"

# Test page retrieval
uv run python3 -c "
from man_server import man_service
import asyncio
content = asyncio.run(man_service.get_man_page('ls', '1'))
print(content[:200] + '...')
"

Using with MCP Inspector

# Run with MCP development tools for debugging
uv run mcp dev man_server.py

Error Handling

The server includes comprehensive error handling:

• Missing pages: Graceful handling with informative error messages
• Timeout protection: Subprocess calls are protected with configurable timeouts
• Fallback methods: If apropos fails, falls back to man -k
• Content validation: Ensures retrieved content is not empty
• Clean formatting: Removes ANSI codes and formatting for AI consumption

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.