Content
# MCP Server.exe
> MCP Launcher by 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: Support 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: Support dynamic loading and configuration of custom tools
- Flexible Deployment: From standalone operation to distributed deployment, meeting various integration scenarios
- Auto reload for config changes
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: Support 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: Support dynamic loading and configuration of custom tools
- Flexible Deployment: From standalone operation to distributed deployment, meeting various integration scenarios
- Auto reload for config changes
### Usage
```bash
# Recommended: Run via CLI (no local build required)
npx mcp_exe --mcp-config ./examples/mcp.json
# Or run the packaged executable (Windows/macOS)
./executables/mcp_server-win-x64.exe --mcp-config ./examples/mcp.json
```
## 🎯 Main Usage Scenarios
### 1. WebSocket Connection Mode
Support 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.
Support 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
# Start in WebSocket mode
npx mcp_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"
}
},
"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, or start via npx.
The simplest way - double-click to run, or start via npx.
```bash
# Double-click to run mcp_server.exe, or start via command line
./executables/mcp_server-win-x64.exe
# Or
npx mcp_exe
```
Default Configuration:
- Listen Port: 3000 (can be modified via `--port`)
- SSE Endpoints: GET `/` to establish a session, POST `/sessions?sessionId=...` to send messages
- Built-in Basic Tools
- Auto reload `--mcp-config` and `--mcp-js`
### 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.
Use the same **mcp.json** configuration file as **Cursor** to combine multiple MCP services, supporting both SSE and stdio transport modes simultaneously.
```bash
npx mcp_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"] }
},
"serverInfo": { "serverName": "dynamic-mcp-server" },
"tools": [],
"namespace": "."
}
```
- `tools`: Allowed tool whitelist (empty array means no filtering)
- `namespace`: Combination namespace separator, default `.` (can also use `::`)
### 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.
Support combining multiple tools into a tool chain to implement complex automation processes. Tool chains can flexibly configure data flow and result output.
```bash
npx mcp_exe --mcp-config ./examples/product-hunt/mcp-tools.json
```
Configuration Example (excerpt, customize as needed):
```json
{
"toolChains": [
{
"name": "product_hunt_news",
"description": "get product hunt news",
"steps": [
{ "toolName": "get_product_hunt_url", "args": {} },
{ "toolName": "load_product_hunt_js_code", "args": {} },
{ "toolName": "browser_navigate", "args": {}, "outputMapping": { "url": "content.0.text" }, "fromStep": 0 },
{ "toolName": "browser_execute_javascript", "args": {}, "outputMapping": { "code": "content.0.text" }, "fromStep": 1 },
{ "toolName": "browser_close", "args": {} }
],
"output": { "steps": [3] }
}
]
}
```
Tool Chain Features:
- Support multi-step sequential execution
- Flexible data flow mapping (`outputMapping`/`fromStep`)
- Can get results from any step (`output.steps`)
### 5. Custom Tools Plugin Mechanism
Flexibly define tools, resources, and prompts through JavaScript configuration files.
Flexibly define tools, resources, and prompts through JavaScript configuration files.
```bash
npx mcp_exe --mcp-js ./examples/custom-mcp-config.js
```
Configuration Example (`custom-mcp-config.js`):
```javascript
module.exports = {
// Recommended export name: configureMcp (also compatible with mcpPlugin)
configureMcp: function(server, ResourceTemplate, z) {
server.tool('myTool', 'Custom Tool Example', { /* zod schema */ }, async (args) => ({ content: [{ type: 'text', text: 'ok' }] }))
server.resource('custom-echo', new ResourceTemplate('custom-echo://{message}', { list: undefined }), async (uri, { message }) => ({ contents: [{ uri: uri.href, text: message }] }))
server.prompt('custom-prompt', { /* zod */ }, ({ message }) => ({ messages: [{ role: 'user', content: { type: 'text', text: message } }] }))
}
}
```
### 6. Cronjob Mode
Use `--cronjob` to execute tools on a schedule. Currently supported operations: `listTools`, `callTool`. The task will be executed immediately upon startup and then periodically according to the `schedule`. Results can be pushed via desktop bubble/email/ntfy.
```bash
# Example: Combine custom tools with cronjobs
npx mcp_exe --cronjob ./examples/cronjob.json --mcp-js ./examples/product-hunt/custom-mcp-config.js
```
Configuration Example (`examples/cronjob.json`):
```json
{
"tasks": [
{
"schedule": "*/30 * * * * *",
"operations": [
{ "type": "callTool", "name": "get_product_hunt_url", "arguments": {} }
],
"notify": [
{ "type": "desktop", "title": "Task Execution Result", "icon": "" }
]
}
]
}
```
Notifications:
- desktop: System bubble (requires local desktop environment)
- email: Send email (requires providing `to`, `subject`, etc.)
- ntfy: Push to `ntfy` (requires providing `url`, `topic`, `tags`, `priority`)
Note: Cronjobs directly call combined tools (including remote SSE/local stdio tools), no need to specify transport in the task.
### 7. Embedded Integration
Integrate as a standalone process into any application.
Integrate as a standalone process into any application.
```javascript
// Node.js Example
const { spawn } = require('child_process')
const mcpServer = spawn('./executables/mcp_server-win-x64.exe', [
'--port', '3000',
'--transport', 'stdio'
])
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:
The server supports the following command line arguments:
| Argument | Description | Default Value |
|------|------|--------|
| `--ws <url>` | WebSocket server address, enable WebSocket connection mode | None |
| `--mcp-js <path>` | MCP JavaScript configuration file path (supports `configureMcp` or `mcpPlugin`) | None |
| `--mcp-config <path/json string>` | MCP JSON configuration file path or JSON string | None |
| `--server-name <name>` | Server name | `mcp_server_exe` |
| `--port <port>` | Server listening port | 3000 |
| `--transport <mode>` | Transport mode, supports `sse` or `stdio` (effective in non-WS mode) | sse |
| `--cronjob <path/json>` | Cronjob configuration file path or JSON string | None |
| `--cursor-link` | Quickly connect in Cursor after startup (SSE mode) | Off |
| `--log-level <level>` | Log level: TRACE/DEBUG/INFO/WARN/ERROR/FATAL/OUTPUT | INFO |
| `--version <version>` `--description <desc>` `--author <author>` `--license <license>` `--homepage <url>` | Meta information | - |
Tip: If `--ws` is provided, WebSocket mode is preferred; otherwise, `sse` is used by default if not explicitly specified.
### Configuration File Format
The server supports using a configuration file to configure both server parameters and MCP functions:
```javascript
module.exports = {
// MCP configuration function
configureMcp: function(server, ResourceTemplate, z) {
// Configure resources and tools
},
// Optional: Provide additional mcp configuration object
mcpConfig: { /* mcpServers/tools/toolChains/namespace */ }
}
```
### Auto Reload
- Listen for `--mcp-config` file changes: automatically re-parse and restart the service (including tool chains/namespaces/tool whitelists, etc.)
- Listen for `--mcp-js` file changes: automatically reload custom `configureMcp`/`mcpPlugin`
### Development Guide
#### Installation
```bash
npm install
```
#### Build
```bash
yarn build # or npm run build
```
#### Run
```bash
npm start
# Or development mode (SSE):
npm run dev
# WebSocket development:
npm run dev-ws
# Cronjob development:
npm run dev-cronjob
```
#### Packaging
```bash
# Windows packaging
npm run package-win
# macOS packaging (Intel/Apple Silicon)
npm run package-mac-intel
npm run package-mac-arm
```
The packaged executable file will be generated in the `executables` directory.
### Logging
- Control the minimum output level via `--log-level` (default `INFO`)
- Console output with timestamp/category/color; `OUTPUT` level is used for verbatim output for tool parsing
### Library API
Since v0.11.x, a stable export is provided: `McpRouterServer`.
```js
// CommonJS
const { McpRouterServer } = require('mcp_exe');
(async () => {
const server = new McpRouterServer({ name: 'my-app' }, { transportType: 'sse', port: 3000 });
await server.importMcpConfig(require('./mcp.json'), null);
await server.start();
})();
```
```ts
// TypeScript / ESM
import { McpRouterServer } from 'mcp_exe';
const server = new McpRouterServer({ name: 'my-app' }, { transportType: 'stdio' });
await server.importMcpConfig(mcpJson, null);
await server.start();
```
- Type declarations are output in `dist/index.d.ts`, automatically exposed via `types`/`exports`.
- CLI is still provided via `bin/cli.js`, the library and CLI can be used in parallel.
## 📝 License
MIT
