Lite MCP
A simple lightweight Model Context Protocol (MCP) server integration framework
Installation
npx lite-mcpAsk AI about Lite MCP
Powered by Claude Β· Grounded in docs
I know everything about Lite MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.pydirectly. The following examples are completed usingmanage.shon 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
-
Python Environment: Ensure Python 3.12+ is installed and added to PATH environment variable
python --version -
Wrapper Script: Now you can use
scripts\manage.batto get the same experience as Linux/macOS -
Multiple Python Commands: The wrapper will automatically detect
python,python3orpycommandsNote: Launch PowerShell or CMD with administrator privileges to execute script commands.
macOS/Linux User Notes
- Execution Permission: Ensure the script has execution permission
chmod +x scripts/manage.sh - 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 enabledmcp server,api server, andproxy 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
π§ 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
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:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
Commit Message Convention
Please use one of the following prefixes for your commit messages:
feat:- New featurefix:- Bug fixdocs:- Documentation changesstyle:- Code formatting (no functional changes)refactor:- Code refactoringtest:- Adding or updating testschore:- 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.

