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?

Installation
- Clone the repository and install dependencies with either uv sync (recommended) or pip install ..
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).
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.

This server is packaged as an MCPB (MCP Bundle) for easy integration with GitHub Copilot in VS Code.

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

Requirements

Operating System: Linux with standard man page system
Python: 3.10 or higher
System Commands: man, apropos (usually pre-installed on Linux)
Dependencies: MCP library (bundled in MCPB or installed via package managers)

Installation

Quick Start with MCPB Bundle

The easiest way to use this server is with the MCPB bundle, which is supported by Claude Desktop:

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

# Build the MCPB bundle
make build

# This creates dist/man-mcp-{version}.mcpb

Installing in Claude Desktop

Open Claude Desktop settings
Navigate to the MCP section
Add the generated dist/man-mcp-{version}.mcpb bundle file

Development Installation

Using uv (recommended)

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

# 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.git
cd man-mcp

# 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 for Development

# Using uv
uv run python3 server/main.py

# Using python directly
python3 server/main.py

# With MCP development tools
uv run mcp dev server/main.py

Building and Using MCPB Bundle

# Build the bundle
make build

# Test the bundle
make test

# View bundle information
make info

VS Code Integration

This MCP server can be integrated with VS Code using the GitHub Copilot extension. Since GitHub Copilot does not yet support MCPB bundles, direct configuration is required for VS Code.

Configuration for GitHub Copilot

Create a .vscode/mcp.json file in your workspace with the following configuration:

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

Alternative: Using python directly

If you prefer not to use uv, you can configure it with python directly:

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

MCP Bundle Support

MCP bundles are supported by Claude Desktop and can be installed directly. For other MCP clients like GitHub Copilot, use the manual configuration above.

Note: Replace /path/to/man-mcp with the actual path to your project directory.

Once configured, you can interact with the man pages server through GitHub Copilot in VS Code by asking questions about Linux commands and system documentation.

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

Troubleshooting

Development

Available Make Commands

# Build the MCPB bundle
make build

# Test the bundle and server functionality
make test

# Show bundle information
make info

# Clean build artifacts
make clean

# Show all available targets
make help

Using with MCP Inspector

# Run with MCP development tools for debugging
uv run mcp dev server/main.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