• English (Default)
• 中文版

• Introduction
• Features
• Architecture
• Getting Started
• Building from Source
• Configuration
• Authentication
• HTTPS and Certificate Generation
• Plugins
• API Reference
• Docker Deployment
• CI/CD Pipeline
• Contributing
• License

MCPServer.cpp is a high-performance, cross-platform server implementation of the Model Communication Protocol (MCP) written in modern C++. It enables seamless communication between AI models and external tools, providing a standardized interface for extending model capabilities.

The server implements the JSON-RPC 2.0 protocol over HTTP transport and supports both regular request-response and Server-Sent Events (SSE) streaming for real-time communication.

• Full implementation of the Model Communication Protocol (MCP)
• JSON-RPC 2.0 over HTTP/HTTPS transport
• Plugin system for extending functionality
• Built-in tools (echo, file operations, HTTP requests, system commands)
• Streaming responses with Server-Sent Events (SSE)
• Comprehensive logging and error handling
• 🚀 High Performance: Built with C++20 and optimized with mimalloc for superior performance
• 🔌 Plugin System: Extensible architecture with dynamic plugin loading
• 🌐 HTTP Transport: Full HTTP/1.1 support with SSE streaming capabilities
• 📦 JSON-RPC 2.0: Complete implementation of the JSON-RPC 2.0 specification
• 🛠️ Built-in Tools: Includes file operations, HTTP requests, and system commands
• 🧠 AI Model Ready: Designed specifically for AI model integration
• 🔄 Asynchronous I/O: Powered by ASIO for efficient concurrent handling
• 📊 Logging: Comprehensive logging with spdlog
• 📈 Scalable: Multi-threaded architecture for handling concurrent requests
• 🌍 Cross-platform: Works on Windows, Linux, and macOS
• 📁 Resource Management: Expose data and content to LLMs via Resources primitive

MCPServer.cpp uses a modular architecture with clear boundaries between components:

┌─────────────────────────────────────────────────────────────┐
│ MCPServer.cpp │
├─────────────────────────────────────────────────────────────┤
│ Transport Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ HTTP Server │ │ Stdio I/O │ │ Other Protocols │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Protocol Layer │
│ ┌──────────────────────┐ │
│ │ JSON-RPC 2.0 │ │
│ └──────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Business Logic Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Tool Reg. │ │ Plugins │ │ Request Processing │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Core Services │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Logger │ │ Resources │ │ Configuration │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

1. Transport Layer: Handles communication over various protocols (HTTP, stdio, etc.)
2. Protocol Layer: Implements JSON-RPC 2.0 message parsing and formatting
3. Business Logic Layer: Manages tools, plugins, and request processing
4. Core Services: Provides essential services like logging

• C++20 compatible compiler (MSVC, GCC 10+, Clang 12+)
• CMake 3.23 or higher
• Git

1. Clone the repository:

   git clone https://github.com/caomengxuan666/MCPServer.cpp.git
   cd MCPServer.cpp

2. Build the project:

   mkdir build
   cd build
   cmake ..
   cmake --build .

3. Run the server:

   ./bin/mcp-server++

The server will start on the default port and load the built-in plugins.

mkdir build
cd build
cmake ..
cmake --build . --config Release

mkdir build
cd build
cmake ..
make -j$(nproc)

See Configuration section for details on how to configure the server.

MCPServer++ supports authentication mechanisms to secure your server from unauthorized access. See AUTH.md for detailed information on how to configure and use authentication.

MCPServer++ supports secure communication over HTTPS. By default, HTTPS is disabled for security reasons and must be manually enabled in the configuration file.

To enable HTTPS:

1. Set enable_https=1 in your config.ini
2. Ensure you have valid SSL certificate files
3. Configure the required SSL file paths

There are two ways to generate SSL/TLS certificates for development and testing:

1. Using the built-in generate_cert tool (recommended)
2. Using OpenSSL command line tools

For detailed instructions on both methods, please refer to the HTTPS and Certificate Generation documentation.

MCPServer.cpp supports a powerful plugin system that allows extending functionality without modifying the core server. Plugins are dynamic libraries that implement the MCP plugin interface.

• file_plugin: File system operations
• http_plugin: HTTP client functionality
• safe_system_plugin: Secure system command execution
• example_stream_plugin: Streaming data example

MCPServer++ now supports Python plugins through a new Python SDK that makes plugin development more intuitive. Python plugins are compiled to dynamic libraries (DLL/SO) that wrap Python code using pybind11.

To create a new Python plugin, use the plugin_ctl tool:

./plugin_ctl create -p my_python_plugin

This will generate a Python plugin template that uses the new Python SDK with decorators and helper functions.

• Decorator-based tool definition with @tool
• Automatic JSON handling
• Streaming tool support
• Parameter validation helpers
• Easy integration with the MCP protocol

For detailed information about Python plugin development, see Python Plugins Documentation.

See plugins/README.md for detailed information on developing custom plugins.

The server implements the JSON-RPC 2.0 protocol over HTTP. All requests should be sent to the /mcp endpoint.

MCPServer++ provides basic support for the MCP Resources primitive, which allows exposing data and content to LLMs. Resources can be accessed through the following JSON-RPC methods:

• resources/list: List available resources
• resources/read: Read the content of a specific resource
• resources/write: Write content to a specific resource (if permitted)

{
 "jsonrpc": "2.0",
 "id": 2,
 "method": "resources/read",
 "params": {
 "name": "example.txt"
 }
}

{
 "jsonrpc": "2.0",
 "id": 2,
 "result": {
 "content": "This is the content of the example resource.",
 "contentType": "text/plain",
 "lastModified": "2025-05-13T10:00:00Z"
 }
}

{
 "jsonrpc": "2.0",
 "id": 1,
 "method": "tools",
 "params": {}
}

{
 "jsonrpc": "2.0",
 "id": 1,
 "result": [
 {
 "name": "read_file",
 "description": "Read a file",
 "inputSchema": {
 "type": "object",
 "properties": {
 "path": {
 "type": "string",
 "description": "Path to the file to read"
 }
 },
 "required": ["path"]
 }
 }
 ]
}

1. Multi-stage build (Image size optimized to 10-15MB)

   docker build -t mcp-server .
   docker run -p 6666:6666 -v $(pwd)/plugins:/plugins -v $(pwd)/certs:/certs mcp-server

2. HTTPS Configuration (Certificate directory mounting required)

   # Enable HTTPS by setting enable_https=1 in config.ini
   # Certificate files must be placed in /certs directory inside container
   docker run -p 6667:6667 -v $(pwd)/certs:/certs mcp-server

• Plugin Path Mapping: Container plugin directory is /plugins, recommend mapping local directory via volume
• Plugin Loading: Supports runtime hot-loading (ensure correct file permissions)

• Based on minimal gcr.io/distroless/cc-debian12 base image
• Static linking + debug info stripping (LTO optimized)
• Domestic users can configure mirror accelerators (see configuration examples)

Pre-built Docker images are available on Docker Hub: https://hub.docker.com/r/mgzy/mcp-server

You can pull and run the latest image directly:

docker pull mgzy/mcp-server
docker run -p 6666:6666 -v $(pwd)/plugins:/plugins -v $(pwd)/certs:/certs mgzy/mcp-server

Our project uses GitHub Actions for continuous integration and deployment. The pipeline automatically builds and tests the server on multiple platforms:

• Ubuntu 22.04 (GitHub Actions latest LTS)
• Ubuntu 24.04 (GitHub Actions latest Ubuntu release)
• Windows Server 2022 (GitHub Actions latest Windows)

We provide two build variants to suit different needs:

1. Full build: Includes all libraries and development headers
2. Minimal build: Contains only the executable and essential files (no development headers or libraries)

The CI/CD pipeline generates packages in multiple formats:

• Windows: ZIP, NSIS installer (EXE)
• Linux: DEB, RPM, TAR.GZ, ZIP

We welcome contributions from the community! Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

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

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