Content
# MCP Server.exe
> MCP Launcher for Cursor & Xiaozhi - 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 a wealth of advanced features:
- Tool Chain Execution: Supports the sequential combination of multiple tools to achieve complex automation processes
- 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 Options: From standalone operation to distributed deployment, catering to various integration scenarios
- Auto Reload: Monitors changes to `--mcp-config` and `--mcp-js`, automatically restarting to apply 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
Supports connecting to other MCP services via WebSocket, particularly suitable for integration with services like xiaozhi.me. Through configuration files, you can easily connect multiple MCP services to xiaozhi.me.
```bash
# Connect to xiaozhi.me using configuration file / 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": "MCP server instance for WebSocket client",
"author": "shadow"
}
}
```
WebSocket Mode Features:
- Supports 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.
```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 with `--port`)
- SSE Endpoints: GET `/` to establish a session, POST `/sessions?sessionId=...` to send messages
- Built-in Basic Tools
- Auto reload for `--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. This allows for selecting the appropriate transport method based on different application scenarios, enhancing system flexibility and scalability.
```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 (an empty array means no filtering)
- `namespace`: Combination namespace separator, default is `.` (can also use `::`)
### 4. Tool Chain Execution
Supports 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:
- Supports 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.
```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`. Tasks will execute immediately upon startup and then according to the `schedule`, with results sent via desktop notifications/email/ntfy.
```bash
# Example: Combine custom tools with cronjob
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": "" }
]
}
]
}
```
Notification Support:
- desktop: System notifications (requires local desktop environment)
- email: Send emails (requires `to`, `subject`, etc.)
- ntfy: Push to `ntfy` (requires `url`, `topic`, `tags`, `priority`)
Note: Cronjobs directly call the combined tools (including remote SSE/local stdio tools) without needing to specify transport in the task.
### 7. Embedded Integration
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 to customize its behavior:
| Argument | Description | Default Value |
|----------|-------------|---------------|
| `--ws <url>` | WebSocket server address, enables WebSocket connection mode | None |
| `--mcp-js <path>` | Path to MCP JavaScript configuration file (supports `configureMcp` or `mcpPlugin`) | None |
| `--mcp-config <path/json string>` | Path to MCP JSON configuration file or JSON string | None |
| `--server-name <name>` | Server name | `mcp_server_exe` |
| `--port <port>` | Server listen port | 3000 |
| `--transport <mode>` | Transport mode, supports `sse` or `stdio` (effective in non-WS mode) | sse |
| `--cronjob <path/json>` | Path to cronjob configuration file or JSON string | None |
| `--cursor-link` | Quick access 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>` | Metadata | - |
Tip: If `--ws` is provided, WebSocket mode takes precedence; otherwise, it defaults to `sse` if not explicitly specified.
### Configuration File Format
The server supports using configuration files to configure both server parameters and MCP functionality:
```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
- Monitors changes to the `--mcp-config` file: automatically re-parses and restarts the service (including tool chains/namespaces/tool whitelists, etc.)
- Monitors changes to the `--mcp-js` file: automatically reloads 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 files will be generated in the `executables` directory.
### Logging
- Control the minimum output level with `--log-level` (default is `INFO`)
- Console output includes timestamps/categories/colors; `OUTPUT` level is used for raw output for tool parsing
### Using as a Library
Since v0.11.x, stable export: `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 to `dist/index.d.ts`, automatically exposed through `types`/`exports`.
- CLI is still provided via `bin/cli.js`, and the library and CLI can be used in parallel.
## 📝 License
MIT
