Content
# MCP Server.exe
> MCP Launcher for XiaoZhi & Cursor - MCP For Cursor&xiaozhi
MCP Server.exe is a powerful executable server that not only runs standard MCP (Model Context Protocol) services but also provides rich advanced features:
- Tool Chain Execution: Supports sequential combination of multiple tools for complex automation
- Multiple MCP Services: Can run and manage multiple MCP services simultaneously, supporting both SSE and stdio modes
- Pluggable Tool System: Supports dynamic loading and configuration of custom tools
- Flexible Deployment: From standalone operation to distributed deployment, meeting various integration scenarios
### Usage
```bash
npx mcp_exe --mcp-config xxx
```
## 🎯 Main Usage Scenarios
### 1. WebSocket Connection Mode
Supports connecting to other MCP services via WebSocket, especially suitable for connecting to WebSocket-enabled MCP services like xiaozhi.me. Through configuration files, you can easily integrate multiple MCP services with xiaozhi.me.
```bash
# Use configuration file to connect to xiaozhi.me
# Start in WebSocket mode
./mcp_server.exe --ws wss://api.xiaozhi.me/mcp/?token=...xxx --mcp-config ./examples/mcp-sse.json
```
Configuration Example (mcp-sse.json):
```json
{
"mcpServers": {
"Model Server sse": {
"url": "http://127.0.0.1:3000"
},
"Model Server - stdio": {
"command": "xxxxx",
"args": [
"--transport",
"stdio"
]
}
},
"serverInfo": {
"serverName": "ws-client-mcp-server",
"version": "1.0.0",
"description": "WebSocket client MCP server instance",
"author": "shadow"
}
}
```
WebSocket Mode Features:
- Support real-time bidirectional communication
- Automatic reconnection mechanism
- Unified management of multiple services
- Compatible with standard MCP protocol
Related Project: [Visual xiaozhi-mcp Launcher](https://github.com/shadowcz007/xiaozhi-mcp-client)
### 2. Quick Start Standalone Service
The simplest way - double-click to run, and start a standard MCP service.
```bash
# Double-click mcp_server.exe, or start via command line:
./mcp_server.exe
```
Default Configuration:
- Listen Port: 3000
- Standard Endpoints: /mcp, /sse, /messages
- Built-in Basic Tools
### 3. Combine Multiple MCP Services
Use the same **mcp.json** configuration file as **Cursor** to combine multiple MCP services, supporting both SSE and stdio transport modes simultaneously. This allows you to choose the appropriate transport method for different application scenarios, improving system flexibility and scalability.
```bash
./mcp_server.exe --mcp-config ./examples/mcp.json
```
Configuration Example (mcp.json):
```json
{
"mcpServers": {
"Model Server - sse": {
"url": "http://127.0.0.1:9090"
},
"Model Server - stdio": {
"command":
"xxx",
"args": ["--transport", "stdio"]
}
}
}
```
### 4. Tool Chain Execution
Support combining multiple tools into a tool chain to implement complex automation processes. Tool chains can flexibly configure data flow and result output.
```bash
./mcp_server.exe --mcp-config ./examples/product-hunt/mcp-tool.json
```
Configuration Example (tool-chain.json):
```json
{
"toolChains": {
"browser_automation": {
"name": "browser_automation",
"description": "Automated browser operation process",
"steps": [
{
"toolName": "browser_navigate",
"args": {
"url": "https://example.com"
}
},
{
"toolName": "browser_execute_javascript",
"args": {
"code": "document.title"
},
"outputMapping": {
"selector": "content.0.text"
}
},
{
"toolName": "browser_close",
"args": {},
"fromStep": 0
}
],
"output": {
"steps": [1] // Only output the result of the second step
}
}
}
}
```
Tool Chain Features:
- Support multi-step sequential execution
- Flexible data flow mapping
- Can get results from any step
- Customize output step results
### 5. Custom Tools Plugin Mechanism
Flexibly define tools, resources, and prompts through JavaScript configuration files.
```bash
./mcp_server.exe --mcp-js ./my-custom-tools.js
```
Configuration Example (my-custom-tools.js):
```javascript
module.exports = {
configureMcp: function(server, ResourceTemplate, z) {
// Add custom tool
server.tool({
name: "myTool",
description: "Custom tool example",
parameters: {
// ... Parameter definitions
}
});
// Add custom resource
server.resource(/* ... */);
}
}
```
### 6. Scheduled Task Mode (Documentation to be supplemented)
--cronjob for scheduled execution of tool
### 7. Embedded Integration
Integrate as a standalone process into any application.
```javascript
// Node.js Example
const { spawn } = require('child_process');
const mcpServer = spawn('./mcp_server.exe', [
'--port', '3000',
'--transport', 'stdio' // Use stdio mode for IPC
]);
// Handle I/O
mcpServer.stdout.on('data', (data) => {
// Handle MCP server output
});
mcpServer.stdin.write(JSON.stringify({
// Send request to MCP server
}));
```
## 📚 Detailed Documentation
### Command Line Arguments
The server supports the following command line arguments to customize its behavior:
| Argument | Description | Default Value |
|----------|-------------|---------------|
| `--ws <url>` | WebSocket server address, enable WebSocket connection mode | None |
| `--mcp-js <path>` | Configuration file path (including server configuration and MCP configuration) | Built-in configuration |
| `--port <port>` | Server listen port | 3000 |
| `--mcp-config <path/json string>` | MCP configuration file path/json string for combining multiple MCP services | None |
| `--transport <mode>` | Transport mode, supports 'sse' or 'stdio' | sse |
### Configuration File Format
The server supports using a configuration file to configure both server parameters and MCP functionality:
```javascript
module.exports = {
// MCP configuration function
configureMcp: function(server, ResourceTemplate, z) {
// Configure resources and tools
}
};
```
### Development Guide
#### Installation
```bash
npm install
```
#### Build
```bash
npm run build
```
#### Run
```bash
npm start
# Or development mode
npm run dev
```
#### Packaging
```bash
# Package for Windows
npm run package-win
# Package for macOS
npm run package-mac
```
The packaged executable files will be generated in the `executables` directory.
### Environment Variables
- `PORT` - Server port (default: 3000)
## 📝 License
MIT
