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

1. Open Claude Desktop settings
2. Navigate to the MCP section
3. 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 pag

... [View full README on GitHub](https://github.com/guyru/man-mcp-server#readme)