Man Mcp Server

What is Man Mcp Server about?

Man Mcp Server enables AI assistants and other tools to query the host's man‑page database. It wraps standard Linux utilities (apropos, man) in asynchronous MCP resources, returning plain‑text content suitable for downstream processing.

How to use Man Mcp Server?

1. Install – clone the repository and install dependencies using either uv:

   git clone https://github.com/guyru/man-mcp-server.git
   cd man-mcp-server
   uv sync
   

   or pip:

   pip install .
   

2. Run the server – start the Python script:

   uv run python3 man_server.py
   # or simply
   python3 man_server.py
   

3. Interact – call the provided asynchronous functions (search_man_pages, get_man_page, list_man_sections) from your code or use the MCP URI scheme (man://search/keyword, man://1/ls).
4. VS Code integration – add a .vscode/mcp.json configuration pointing to the script (example shown in the README).

Key Features

• Keyword‑based search via apropos with fallback to man -k
• Retrieve full man‑page content by name and optional section
• List all man‑page sections (1‑9) with human‑readable descriptions
• Asynchronous execution with configurable timeout protection
• Automatic cleaning of ANSI codes and formatting for AI consumption
• MCP resource exposure using man:// URIs

Use Cases

• Enabling AI chat assistants to answer Linux command questions with authoritative documentation
• Building CLI tools that need programmatic access to man pages without spawning interactive man
• Integrating system documentation into IDEs or developer portals via MCP
• Automated testing of command‑line utilities that require reference to official man pages

FAQ

Q: Which operating systems are supported? A: Any Linux distribution that provides the standard man and apropos commands.

Q: Do I need root privileges? A: No, the server only reads existing man‑page files; normal user permissions are sufficient.

Q: Can I specify a custom timeout? A: Yes, the service reads a timeout value from its configuration (default is 5 seconds).

Q: How are resources accessed? A: Via MCP URIs such as man://search/network, man://3/printf, or man://sections.

Q: Is the project open source? A: Yes, it is licensed under the MIT License.

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.