Mcp Unix Manual

MCP Unix Manual

A Model Context Protocol (MCP) server that provides access to Unix manual pages directly within Claude. Query man pages, search documentation, and explore Unix commands without leaving your conversation.

Features

• Read Manual Pages: Get the full text of any Unix man page
• Search Documentation: Find commands by keyword using apropos
• Browse Sections: Explore the standard Unix manual page sections
• macOS Native: Built with Swift for optimal performance on macOS

Available Tools

Tool	Description	Parameters
read_manpage	Read a Unix manual page	command (required), section (optional)
search_manpages	Search man pages by keyword	query (required)
list_man_sections	List standard manual sections	None

Example Usage

Claude, can you read the man page for grep?
Claude, search for commands related to "network"
Claude, show me the list of manual sections

Requirements

• macOS 13.0 or later
• Swift 6.2 or later
• Xcode (for building)

Installation

1. Build the Server

Clone the repository and build a release version:

git clone <repository-url>
cd MCPUnixManual
swift build -c release

The executable will be located at .build/release/mcp-unix-manual.

2. Configure Claude Desktop

Step 1: Locate the Configuration File

Open the Claude Desktop configuration file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the file doesn't exist, create it:

mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: Add the MCP Server

Add the following configuration to claude_desktop_config.json:

{
  "mcpServers": {
    "unix-manual": {
      "command": "/absolute/path/to/MCPUnixManual/.build/release/mcp-unix-manual"
    }
  }
}

Important: Replace /absolute/path/to/MCPUnixManual with the actual absolute path to your cloned repository.

To find the absolute path, run this in your project directory:

pwd

Then use that path in your configuration. For example:

{
  "mcpServers": {
    "unix-manual": {
      "command": "/Users/yourname/Projects/MCPUnixManual/.build/release/mcp-unix-manual"
    }
  }
}

Step 3: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

Step 4: Verify Integration

Open Claude Desktop and look for the MCP icon (🔌) in the bottom right corner. Click it to see available MCP servers - you should see "unix-manual" listed.

You can now ask Claude to use the Unix manual tools:

• "Read the man page for ls"
• "Search for commands related to processes"
• "What are the Unix manual sections?"

Troubleshooting

MCP server not appearing:

• Verify the path in claude_desktop_config.json is absolute and correct
• Check that the executable has execute permissions: chmod +x .build/release/mcp-unix-manual
• Ensure you've restarted Claude Desktop completely

Permission errors:

• Make sure the executable is built and accessible
• Try running the executable directly to check for errors: .build/release/mcp-unix-manual

JSON syntax errors:

• Validate your claude_desktop_config.json syntax
• Ensure there are no trailing commas in the JSON

Claude Code Integration

For Claude Code (CLI), add the following to your MCP settings file:

{
  "mcpServers": {
    "unix-manual": {
      "command": "/absolute/path/to/MCPUnixManual/.build/release/mcp-unix-manual"
    }
  }
}

Development

Running in Development Mode

swift run mcp-unix-manual

Running Tests

swift test

Project Structure

MCPUnixManual/
├── Package.swift              # Swift package manifest
├── Sources/
│   └── MCPUnixManual/
│       └── MCP.swift         # Main server implementation
└── README.md

Security

This MCP server executes shell commands (man, apropos) to retrieve Unix manual pages. Input validation is performed to prevent command injection:

• Only alphanumeric characters, dots, hyphens, and underscores are allowed in command names
• Arguments are properly escaped before execution
• Commands run with the same permissions as Claude Desktop

Platform Support

• macOS: Full support (uses Foundation.Process)
• iOS/tvOS/watchOS/visionOS: Compiles but returns error messages (Process unavailable)

This is intentional - Unix manual pages are only available on macOS.

License

[Add your license here]

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Credits

Built with the MCP Swift SDK by Anthropic.