oh-my-mcp

A powerful Model Context Protocol (MCP) server with 116 practical tools across 9 categories, built using FastMCP.

🚀 Features

oh-my-mcp provides tools for:

• 📦 Compression (5 tools): ZIP/TAR compression and extraction with security features
• 🌐 Web & Network (18 tools): Web search, page fetching, HTML parsing, downloads, HTTP API client, DNS lookup
• 📁 File System (12 tools): Read, write, search files and directories, file comparison
• 📊 Data Processing (15 tools): JSON, CSV, XML, YAML, TOML parsing and manipulation
• 📝 Text Processing (9 tools): Regex, encoding, email/URL extraction, text similarity
• 💻 System (8 tools): System info, CPU/memory monitoring, environment variables
• 🛠️ Utilities (10 tools): UUID, hashing, date/time operations, math, password generation
• 🤖 Subagent AI (6 tools): Delegate subtasks to external AI models (OpenAI/Anthropic), parallel execution, conditional branching, persistent config
• 🌐 Browser Automation (33 tools): Selenium-based browser control, page navigation, element interaction, screenshots, JavaScript execution, multi-tab management

Note: Python Development, UV Package Manager, and Pylance/Pyright tools have been removed from the packaged version as they require external Python interpreters and package managers. All remaining tools work completely standalone.

📚 Documentation

• 📖 Documentation Index - Complete documentation hub (中文)
• 🏗️ Project Structure - Detailed project organization
• 🎯 Setup Guide - Interactive configuration wizard guide
• 📦 Build Guide - Package for Windows/Linux distribution
• 🏛️ Architecture Guide - System architecture and design
• 🧪 Subagent Guide - AI orchestration features

⚡ 快速安装与配置

1. 安装依赖并开发模式安装：

pip install -e .

2. 运行交互式配置向导（推荐）：

uv run configure.py

或直接为Claude Desktop生成配置：

python -m mcp_server.cli.config --claude

或启动HTTP配置服务：

python -m mcp_server.cli.config --http-server --port 8765

详细配置说明见：docs/zh/SETUP_GUIDE.md

3. 启动MCP服务：

python -m mcp_server.main

启动后可通过Claude Desktop或MCP客户端连接使用。

📦 Installation

Prerequisites

• Python 3.12 or higher
• pip package manager

---

---

📚 Tool Reference

For the full list of tools, usage examples, and API details, see docs/en/TOOL_REFERENCE.md.

🔧 Configuration

Logging

Logs are configured in mcp_server/utils.py. You can adjust:

• Log level (INFO, DEBUG, WARNING, ERROR)
• Output destinations (console, file)
• Log format

File Size Limits

File operations have safety limits:

• read_file: 10MB max file size
• safe_write_file: Creates parent directories automatically

Security Features

• Path validation: Prevents path traversal attacks
• Safe evaluation: Math expressions only allow safe operations
• Masked values: Sensitive environment variables are masked
• Confirmation required: File deletion requires confirm=True
• Retry logic: Network operations retry up to 3 times

---

🛡️ Error Handling

All tools include comprehensive error handling:

• ValidationError: Invalid input parameters
• NetworkError: Network request failures
• FileOperationError: File system errors
• DataProcessingError: Data parsing/conversion errors

Errors are returned as JSON with descriptive messages.

---

📝 Development

Project Structure

oh-my-mcp/
├── pyproject.toml               # Dependencies
├── configure.py                 # Interactive setup wizard
├── README.md                    # Documentation
└── src/
    └── mcp_server/
        ├── __init__.py              # Package init
        ├── main.py                  # Server entry point
        ├── utils.py                 # Infrastructure & utilities
        ├── command_executor.py      # Secure command execution
        ├── cli/
        │   └── config.py            # Configuration generator
        └── tools/                   # Tool plugins (9 categories)
            ├── __init__.py          # Plugin auto-discovery
            ├── registry.py          # @tool_handler & ToolPlugin
            ├── search_engine.py     # Web search backend
            ├── subagent_config.py   # Subagent config manager
            ├── compression/         # Compression tools (5)
            ├── web/                 # Web & Network tools (18)
            ├── file/                # File System tools (12)
            ├── data/                # Data Processing tools (15)
            ├── text/                # Text Processing tools (9)
            ├── system/              # System tools (8)
            ├── utility/             # Utility tools (10)
            └── subagent/            # AI Orchestration tools (6)

Adding New Tools

Create a new tool in the appropriate plugin's handlers.py:

from mcp_server.tools.registry import tool_handler

@tool_handler
def your_tool(param: str) -> str:
    """Tool description.

    Args:
        param: Parameter description

    Returns:
        Return value description
    """
    try:
        # Your implementation
        return result
    except Exception as e:
        logger.error(f"Tool failed: {e}")
        return f"Error: {str(e)}"

Testing

Start the server and test tools using an MCP client or the FastMCP testing utilities.

---

🤝 Contributing

Contributions are welcome! Areas for improvement:

• Additional tool categories
• Enhanced error handling
• Performance optimizations
• More comprehensive tests
• Additional external API integrations

---

📄 License

This project is provided as-is for educational and practical use.

---

🔗 Links

• FastMCP Documentation
• Model Context Protocol (MCP)
• DuckDuckGo Search

---

📖 Additional Resources

Documentation

• 📚 Documentation Hub - Complete documentation index (中文)
• 🏗️ Project Structure - Project organization guide
• 🏛️ Architecture - System architecture and design
• 📋 Test Report - Test suite

Configuration & Setup

• ⚙️ Configuration Guide (CN) - Complete configuration reference
• 🎯 Setup Guide - Step-by-step setup instructions

Build & Deploy

• 📦 Build Guide - Package for Windows/Linux
• 🚀 Installation Guide - Installation details

Advanced Features

• 🤖 Subagent Configuration - AI task delegation setup
• 🧠 Subagent Guide - AI orchestration features
• 🔍 Advanced Search - Search functionality details

Developer Resources

• 🏛️ Architecture Guide - System architecture and design
• 🤝 Contributing Guide - How to contribute
• 📝 Changelog - Version history

---

🔧 Configuration Management

Configuration Generator Tool

The python -m mcp_server.cli.config command provides multiple ways to configure MCP clients:

# Quick install to Claude Desktop
python -m mcp_server.cli.config --claude

# Run HTTP server on custom port
python -m mcp_server.cli.config --http-server --port 9000

# Generate config file with custom server name
python -m mcp_server.cli.config --server-name my-tools --output config.json

# Show configuration in console
python -m mcp_server.cli.config --show-config

Configuration Server Endpoints

When running with --http-server:

Endpoint	Description
GET /config	Returns MCP configuration JSON
GET /info	Returns server information and paths
GET /health	Health check endpoint

Example usage:

# Start server on port 8765
python -m mcp_server.cli.config --http-server

# Get configuration
curl http://localhost:8765/config

# Get server info
curl http://localhost:8765/info

---

Enjoy oh-my-mcp! 🚀