LiteMCP Framework

English | 中文

A simple Model Context Protocol (MCP) server framework designed to solve issues like scattered nodes, management chaos, and inconsistent access points in current MCP server clusters, providing a concise and efficient tool development and management solution.

LiteMCP Framework fully supports Windows, macOS, and Linux operating systems, ensuring a consistent experience across platforms. Key advantages include:

• Rapid creation of custom testing tools, reducing development costs in multi-server scenarios
• Standardized MCP protocol implementation, resolving protocol compatibility issues between distributed nodes
• Flexible support for multiple deployment modes, adapting to server clusters of different scales
• Simple and extensible architecture, easily handling dynamically growing server counts
• Built-in intelligent proxy server that integrates distributed nodes into a unified access point, eliminating the complexity of managing multiple servers

🚀 Quick Start

🛠️ Environment Requirements

Backend Environment

• Python 3.12+，For multiple Python versions, consider using tools like pyenv for management
• pip 21.2+, Poetry or uv
• Git(for version control)

Frontend Environment (Optional, for Web Interface)

• Node.js 16+(Recommended 18+)
• npm or yarn

Platform	Python Installation Method	Node.js Installation Method
Windows	Python Official Website or Microsoft Store	Node.js Official Website
macOS	Homebrew: brew install python@3.12	brew install node
Linux	System Package Manager: sudo apt install python3.12 (Ubuntu/Debian)	sudo apt install nodejs npm

Starting the Server

Method 1: Using Poetry

# Clone the project
git clone https://github.com/stonehill-2345/lite-mcp.git
cd lite-mcp

# Install Python dependencies
poetry install

# Activate the virtual environment
poetry shell

# Start the backend service
./scripts/manage.sh up

Method 2: Using uv

uv is an extremely fast Python package manager, 10-100 times faster than pip and Poetry.

# Clone the project
git clone https://github.com/stonehill-2345/lite-mcp.git
cd lite-mcp

# Install dependencies using uv (automatically creates a virtual environment)
uv sync

# Activate the virtual environment
source .venv/bin/activate  # Linux/macOS
# or .venv\Scripts\activate  # Windows

# Start the backend service
./scripts/manage.sh up

Method 3: Using pip

# Clone the project
git clone https://github.com/stonehill-2345/lite-mcp.git
cd lite-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or .venv\Scripts\activate  # Windows

# Install dependencies (pip 21.2+ supports direct installation from pyproject.toml)
pip install -e .

# Start the backend service
./scripts/manage.sh up

Method 4: Using Docker (Quick Deployment)

For users who prefer containerized deployment or want to quickly test the system:

# Clone the project
git clone https://github.com/stonehill-2345/lite-mcp.git
cd lite-mcp

# Deploy with Docker (one-command deployment)
cd docker
./deploy.sh up

# Or with custom configuration
FRONTEND_PORT=3000 ./deploy.sh up

Docker Deployment Features:

• ✅ One-command deployment: Complete backend + frontend stack
• ✅ Automatic configuration: No manual environment setup required
• ✅ Isolated environment: No conflicts with existing Python/Node.js installations
• ✅ Production-ready: Includes nginx, health checks, and proper networking

For detailed Docker deployment instructions, see Docker Deployment Guide.

⚡ Quick Verification

# Check service status
./scripts/manage.sh ps

# Test API endpoint
curl http://localhost:9000/api/v1/health

# View available tools
curl http://localhost:9000/api/v1/config

View Log Information

If needed, you can find each server's log information in the runtime/logs folder at the project root path.

cd runtime/logs

Start Web Assistant

Start if needed, ignore if not needed

# Start Web frontend (optional, new terminal window)
cd web
npm install
npm run dev

After successful startup, you can access through the following addresses:

• Backend API: http://localhost:9000
• API Documentation: http://localhost:9000/docs
• Web Interface: http://localhost:2345 (if frontend is started)
• Proxy Service: http://localhost:1888

Detailed Usage Documentation Reference

Management Script Instructions

OS	Recommended Script	Python Version
Linux	./scripts/manage.sh	Python 3.12+
macOS	./scripts/manage.sh	Python 3.12+
Windows	scripts\manage.bat	Python 3.12+
Cross-platform	./scripts/manage.py	Python 3.12+

Get usage parameters:

python ./scripts/manage.py help
./scripts/manage.sh help  # or
./scripts/manage.bat help  # or

# The core of the management script is cli.py, you can even use cli.py directly
python src/cli.py serve --server example --transport sse --port 8000

Basic Usage

Note: Choose the appropriate management script for your system or use manage.py directly. The following examples are completed using manage.sh on Mac OS.

# Install dependencies
poetry install

# Start all services (enabled mcp server, mcp api, mcp proxy), automatically starts services with enabled=true according to the configuration in [servers.yaml](config/servers.yaml)
./scripts/manage.sh up

# View startup status and access addresses
./scripts/manage.sh ps

# Stop all services
./scripts/manage.sh down

# Restart all services, same effect as up parameter
./scripts/manage.sh restart

Advanced Usage

# Start only mcp api
./scripts/manage.sh api

# Start only mcp proxy
./scripts/manage.sh proxy

# Start specified service (service name depends on configuration in [__init__.py](src/tools/__init__.py))
./scripts/manage.sh up --name <server name>

# Stop specified service
./scripts/manage.sh down --name <server name>

# Output detailed debug logs, add --verbose parameter after any management operation to view debug logs generated during the process
./scripts/manage.sh down --name <server name> --verbose

# Restart specified service
./scripts/manage.sh restart --name <server name>

# Register mcp server to specified mcp proxy and provide external services through the proxy
./scripts/manage.sh start --name example --proxy-url <proxy_ip:1888>  # Start specified service and register to proxy

# Unregister all services
./scripts/manage.sh unregister --proxy-url <proxy_ip:1888>

Note: Registering to a remote proxy service is mainly suitable for Jenkins-like multi-slave, one-master mode. When registering to a remote proxy, if the remote proxy also starts this service, it will overwrite the registered service information. !

For remaining non-core parameters, you can explore using ./scripts/manage.sh help.

💡 Platform-Specific Notes

Windows User Notes

1. Python Environment: Ensure Python 3.12+ is installed and added to PATH environment variable

   python --version
   

2. Wrapper Script: Now you can use scripts\manage.bat to get the same experience as Linux/macOS

3. Multiple Python Commands: The wrapper will automatically detect python, python3 or py commands

   Note: Launch PowerShell or CMD with administrator privileges to execute script commands.

macOS/Linux User Notes

1. Execution Permission: Ensure the script has execution permission

   chmod +x scripts/manage.sh
   

2. System Commands: The script will automatically detect the operating system and use corresponding commands

🎯 Configure MCP Client Example

📱 Client Configuration

Get Client Configuration

⚠️Important: You must start the API server before calling the interface to get the configuration (affects configuration retrieval but not stdio mode usage), otherwise you cannot directly call the interface to get configuration information

• Method 1: Run directly: api_server.py. Note: This method only works for stdio mode; sse http mcp servers are not started.
• Method 2: Start via cli: python src/cli.py api. Note: This method only works for stdio mode; sse http mcp servers are not started.
• Method 3: Start api server using management script: ./scripts/manage.sh api. Note: This method only works for stdio mode; sse http mcp servers are not started.
• Method 4: Directly execute the previously mentioned ./scripts/manage.sh up. Note: This method starts all enabled mcp server, api server, and proxy server.
• Method 5:
  • python ./scripts/manage.py api # Start API
  • python ./scripts/manage.py proxy # Start proxy
  • python ./scripts/manage.py up --name xxx # Start specified service

Method 1: Get configuration directly through API

curl -X 'GET' \
  'http://{mcp api ip}:9000/api/v1/config?client_type=cursor&format=json' \
  -H 'accept: application/json'

Method 2: Get through swagger page provided by fast api (or) Open in browser: http://{machine IP where service is started}:9000/docs#/default/get_mcp_config_config_get

Method 3: Directly view the startup log, which will display the proxy address, MCP server startup address, and port number

clientConfiguration Content Description

{
    "sse-proxy": {
        "url": "https://{proxy ip}:1888/sse/pm",
        "description": "[Using proxy, SSE mode] Proxy automatically forwards requests based on path"
    },
   "http-proxy": {
        "url": "https://{proxy ip}:1888/mcp/pm",
        "description": "[Using proxy, Streamable HTTP mode] Proxy automatically forwards requests based on path"
    },
   "sse": {
        "url": "https://{mcp server ip}:8765/sse",
        "description": "[Without proxy, SSE mode] Requests are processed by the specific MCP SSE server without proxy forwarding"
    },
    "mcp": {
        "url": "https://{mcp server ip}:8765/mcp",
        "description": "[Without proxy, Streamable HTTP mode] Requests are processed by the specific MCP HTTP server without proxy forwarding"
    },
    "school-stdio": {
        "command": "/bab/.cache/pypoetry/virtualenvs/litemcp-bQXDpGYe-py3.12/bin/python3",
        "args": [
            "/home/bab/Code/litemcp/src/tools/demo/school_server.py"
        ],
        "env": {},
        "description": "[Local command line mode] Maintained by MCP client"
    }
}

Note: When not using a proxy service, the port may change each time the service is restarted and needs to be adjusted accordingly. The default proxy port is 1888.

Configure Cursor Example

Configure tool path example: Configure content example: Enable tool example: Use tool example:

Server Configuration File

This configuration affects which services are started by startup scripts like manage.sh and manage.py, as well as service-specific configuration parameters. Non-universal parameters are recommended to be hard-coded directly, while more universal necessary configurations can be placed in environment files.

config/servers.yaml configuration example:

# LiteMCP Server Startup Configuration
mcp_servers:
  example:
    enabled: true                    # Whether to enable this server
    server_type: "example"           # Server type
    transport: "sse"                 # Transport protocol: stdio/http/sse  
    host: null                       # Automatically gets current machine IP, externally accessible
    port: null                       # Port number, null for automatic assignment
    auto_restart: true               # Whether to auto-restart
    description: "Example server"

  school:
    enabled: true
    server_type: "school"
    transport: "sse"
    host: null                       # Automatically gets current machine IP, externally accessible
    port: null                       # Port number, null for automatic assignment
    auto_restart: true
    description: "School management server"

# API Server Configuration  
api_server:
  enabled: true                      # Whether to enable API server
  host: null                         # Automatically gets current machine IP, externally accessible
  port: 9000                         # API server port
  auto_restart: true                 # Whether to auto-restart
  description: "Configuration API server"

🏗️ Project Structure

litemcp/
├── src/                  # Backend source code
│   ├── core/             # Core modules
│   ├── tools/            # MCP tool servers
│   ├── controller/       # API controllers
│   └── cli.py            # Command line entry
├── web/                  # Frontend Web interface
│   ├── components/       # Vue components
│   ├── services/         # API services
│   ├── utils/            # Utility functions
│   ├── api/              # API wrappers
│   ├── package.json      # Frontend dependencies configuration
│   ├── vite.config.js    # Vite build configuration
│   └── main.js           # Frontend entry
├── config/               # Configuration files
│   └── servers.yaml      # Server configuration
├── scripts/              # Management scripts
│   ├── manage.sh         # Linux/macOS management script
│   ├── manage.bat        # Windows management script
│   └── manage.py         # Cross-platform Python management script
├── pyproject.toml        # Python Project Configuration (Supports Poetry, uv, and pip)
└── README.md             # Project description

• Project Structure

🔧 Development Guide

Create New Tool Server

Now it only takes 5 steps, no need to modify CLI code!

1. Create Server File

Create a new server file in the tools/ directory

2. Register to Framework

Register the new server in tools/__init__.py

3. Configure Startup Parameters

Add server configuration in config/servers.yaml

4. Test Tool

Use ./scripts/manage.sh up to start batch testing or refer to the "Advanced Usage" section to start individually

5. Verify Functionality

Verify tool functionality in MCP client through proxy address

Example Implementation

"""
My Test Tool - Concise Development Mode
"""

from src.tools.base import BaseMCPServer
    

class MyTestServer(BaseMCPServer):
    """My Test Server - Inherits Base Class"""
    
    def __init__(self):
        # Call parent class initialization to automatically get transport mode support
        super().__init__("My-Test-Server")
    
    def _register_tools(self):
        """Implement tool registration - focus on business logic"""
        
        @self.mcp.tool()
        def my_tool(param: str) -> str:
            """My Test Tool"""
            return f"Processed: {param}"

# Create Instance
my_server = MyTestServer()

if __name__ == "__main__":
    # Automatically supports all transport modes:
    # my_server.run()       # STDIO mode
    # my_server.run_http()  # HTTP mode  
    # my_server.run_sse()   # SSE mode
    my_server.run()

🚨 Troubleshooting

Common Issues

# Port Conflict
./scripts/manage.sh down --force  # Force stop all servers
./scripts/manage.sh up            # Restart

# View Logs
./scripts/manage.sh log           # View all log files
tail -f logs/example.log  # View specific logs in real-time

# System Check
./scripts/manage.sh check         # Health check
poetry install         # Reinstall dependencies

# Detailed Debugging
./scripts/manage.sh up --verbose  # Show detailed startup information
./scripts/manage.sh diagnose      # Run system diagnosis

🔧 Detailed Troubleshooting Guide: Check USAGE.md for complete diagnosis methods and solutions

📚 Complete Documentation Navigation

🚀 Quick Start Documentation

• 5-Minute Quick Start - Environment preparation to tool invocation
• Proxy Server Details - Architecture and usage of intelligent proxy

🛠️ Developer Documentation

• Develop New Tools - Create custom tools in 5 steps
• Transport Modes Details - STDIO, HTTP, SSE, Proxy Mode
• Project Structure - Complete directory structure and file description

🔧 Operations and Maintenance Documentation

• Command List - Detailed explanation of all management commands
• Configuration File Details - Complete configuration explanation for servers.yaml
• Troubleshooting Guide - Common issues and solutions

📖 Core Functionality Documentation

• Intelligent Proxy Server - Architecture principles, configuration, and diagnosis
• Common Operation Scenarios - Development, production, and maintenance scenarios
• Frequently Asked Questions (FAQ) - Detailed Q&A collection

💡 Usage Suggestions:

• New users: First read this README, then check 5-Minute Quick Start
• Developers: Focus on the Develop New Tools section
• Operations personnel: Refer to the Troubleshooting Guide and command list

Built-in Example Services

Server Type	Description	Purpose
example	Example tool server	Development mode demonstration, standardized implementation
school	School management server	Student information management, data operation example

Transport Protocol Support

• STDIO: Standard input/output mode, suitable for local development managed by specific MCP client
• HTTP: RESTful API mode, suitable for network deployment (automatically displays local and external access addresses)
• SSE: Server-Sent Events mode, suitable for Web integration (automatically displays local and external access addresses)
• Proxy Mode: Unified access entry that masks dynamically changing ports of specific MCP servers with automatic path matching forwarding, highly recommended

🤝 Community Integrations

LiteMCP Framework integrates with the following open-source projects and libraries to provide a comprehensive MCP server development experience:

Core Dependencies

• fastmcp - Fast Model Context Protocol implementation for Python
• fastapi - Modern, fast web framework for building APIs with Python
• uvicorn - Lightning-fast ASGI server implementation
• click - Python package for creating beautiful command line interfaces
• rich - Rich library for beautiful terminal output

System & Network

• psutil - Cross-platform library for retrieving information on running processes and system utilization
• httpx - A fully featured HTTP client for Python, with both sync and async APIs
• requests - HTTP library for Python, built for human beings

Data Processing & Security

• PyYAML - YAML parser and emitter for Python
• pycryptodome - Cryptographic library for Python
• chardet - Universal character encoding detector

Database & Utilities

• pymysql - Pure Python MySQL Client Library
• apkutils2 - Android APK file parser and utilities

Development & Testing

• pytest - Framework for writing and running tests in Python
• pytest-asyncio - Pytest plugin for testing async code

Contributing

We welcome contributions from the community! If you'd like to contribute to LiteMCP Framework:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Commit Message Convention

Please use one of the following prefixes for your commit messages:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code formatting (no functional changes)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Example: feat: add new MCP server for file operations

License

This project is licensed under the MIT License - see the LICENSE file for details.