man-mcp-server

What is man-mcp-server?

man-mcp-server is a Model Context Protocol (MCP) server designed to provide AI assistants with seamless access to Linux man pages. It allows AI to search, retrieve, and explore system documentation directly from your local machine, acting as a bridge between AI tools and the comprehensive man page system.

How to use man-mcp-server?

To use man-mcp-server, you first need to install it. You can do this using uv (recommended) or pip:

Using uv:

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

Using pip:

git clone https://github.com/guyru/man-mcp-server.git
cd man-mcp-server
pip install .

Once installed, you can run the server:

Using uv:

uv run python3 man_server.py

Using python directly:

python3 man_server.py

For VS Code integration, create a .vscode/mcp.json file with the appropriate server configuration.

AI assistants can then interact with the server using available tools:

search_man_pages("keyword"): To search for man pages.
get_man_page("page_name", "section"): To retrieve specific man page content.
list_man_sections(): To list available man page sections.

Key Features of man-mcp-server

Search man pages: Efficiently 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 optimal AI consumption.
Async operations: All operations are asynchronous with timeout protection.
MCP Resources: Exposes man pages as resources with man:// URIs (e.g., man://1/ls).
Comprehensive Error Handling: Includes graceful handling for missing pages, timeout protection, fallback methods, content validation, and clean formatting.

Use Cases of man-mcp-server

AI-powered system administration: AI assistants can quickly look up commands, configurations, and system behavior.
Automated troubleshooting: AI can retrieve relevant man pages to diagnose and resolve system issues.
Developer productivity: AI tools can provide instant access to documentation for system calls and libraries.
Educational purposes: AI can be used to explain complex system concepts by referencing man pages.

FAQ about man-mcp-server

Q: What operating systems are supported? A: Linux with a standard man page system is required.

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

Q: What commands are necessary for this server to function? A: The man and apropos commands are required, which are usually pre-installed on Linux systems.

Q: How does it handle errors? A: The server includes robust error handling for missing pages, timeouts, and provides fallback methods if apropos fails. It also validates content and cleans formatting for AI consumption.

Q: Can I integrate this with VS Code? A: Yes, you can integrate it with VS Code by creating a .vscode/mcp.json configuration file.

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:

Create the VS Code MCP configuration directory (if it doesn't exist):
```
mkdir -p .vscode
```

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"]
    }
  }
}

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

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.

man-mcp-server Overview