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

⚡ 快速安装与配置

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

pip install -e .

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

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

启动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

📖 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! 🚀

MCP Servers