MC
Search

MCP Server for Local Man Pages

Search and access local man pages with an MCP server for fast, offline documentation lookup on your machine.

View on GitHub
Quick Install
npx -y @guyru/man-mcp-server

Overview

This MCP (Model Context Protocol) server indexes and serves the man pages installed on your machine, exposing them via a local HTTP/MCP API. Instead of invoking man on the command line or searching compressed files manually, developer tools and LLM agents can query the server to quickly search for and retrieve formatted man page content. The server is designed for offline use, so it works without network access and reads the system man database (e.g., /usr/share/man, /usr/local/man) to build its index.

Running a local MCP server for man pages is useful when you want fast programmatic access to Unix documentation from editors, development tools, CI environments, or AI agents. It reduces latency compared to repeatedly spawning man processes, normalizes output (plain text/markdown), and offers search-by-name, search-by-keyword, and section-specific fetches through a small, consistent API that respects the MCP pattern for context providers.

Features

  • Indexes local man page files (including compressed .gz man pages) from standard man directories
  • Full-text search across man pages (name, short description, body)
  • Retrieve a specific man page by name and section
  • Returns plain text or preformatted HTML/markdown suitable for display or embedding in context windows
  • Lightweight HTTP/MCP API intended for local deployments and offline use
  • Configurable man directories, server port, and result formats
  • Suitable for integration with editors, LLM agents, shells, and other developer tools

Installation / Configuration

Basic steps (clone the repo, install dependencies, and run). Adjust commands per your environment.

Clone the repository:

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

Python-based installation (common pattern):

# create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# install dependencies
pip install -r requirements.txt

# run the server (reads default config or uses CLI flags)
python -m man_mcp_server --config config.yaml

Docker (example pattern; adjust image name if building locally):

# build locally
docker build -t man-mcp-server .

# run and mount your system man directories for indexing
docker run --rm -p 8080:8080 \
  -v /usr/share/man:/man/share \
  -v /usr/local/man:/man/local \
  man-mcp-server

Example config (config.yaml)

server:
  host: 127.0.0.1
  port: 8080

man:
  paths:
    - /usr/share/man
    - /usr/local/man
  default_format: text   # text | markdown | html
index:
  refresh_interval_seconds: 600
  include_sections: [1,2,3,4,5,6,7,8]

Notes:

  • The server usually needs read access to your man directories. If you mount directories into a container, point the server config to the mounted path.
  • The indexer will scan compressed man files (.gz) and plain files; large man trees may take a short time to index on first run.

Available Resources

  • GitHub repository: https://github.com/guyru/man-mcp-server — source, issues, and contribution guidelines
  • Local man directories to index: typically /usr/share/man, /usr/local/man (path is configurable)
  • Output formats: plain text, Markdown, or HTML (choose in config or per-request)

API Examples (MCP-style usage)

The server exposes a small HTTP JSON API compatible with local MCP-style usage patterns. Replace host/port with your configured values.

Search for pages mentioning “socket”:

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "action": "search",
    "query": "socket",
    "limit": 10,
    "format": "text"
  }'

Fetch the man page for ls(1):

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "action": "fetch",
    "name": "ls",
    "section": "1",
    "format": "markdown"
  }'

Example response (abbreviated):

{
  "status": "ok",
  "tool": "man",
  "name": "ls",
  "section": "1",
  "content": "# ls(1)\n\nList directory contents.\n\n## SYNOPSIS\n\nls [OPTION]... [FILE]...\n..."
}

Typical request fields:

  • action: “search” | “fetch”
  • query: text (for search)
  • name: man page name (for fetch)
  • section
Tags:search