Content
<p align="center">
| <a href="./README.EN.md">EN</a>
</p>
# mcp-host-use
**mcp-host-use is a Node.js-based Model Context Protocol (MCP) host application for connecting to and managing multiple MCP servers. The Host provides a unified interface that allows clients to interact with multiple MCP servers through HTTP APIs, accessing and calling tools (or resources). You can use it to quickly test and run your MCP Servers.**
## Architecture Diagram
```mermaid
graph TD
Client[Client] -->|HTTP Request| HostServer[MCP Host Server]
HostServer -->|Manage| ConnectionManager[Connection Manager]
ConnectionManager -->|Create/Manage| MCPClient1[MCP Client 1]
ConnectionManager -->|Create/Manage| MCPClient2[MCP Client 2]
ConnectionManager -->|Create/Manage| MCPClientN[MCP Client N]
MCPClient1 -->|STDIO/SSE/StreamableHTTP| MCPServer1[MCP Server 1]
MCPClient2 -->|STDIO/SSE/StreamableHTTP| MCPServer2[MCP Server 2]
MCPClientN -->|STDIO/SSE/StreamableHTTP| MCPServerN[MCP Server N]
```
## Key Features
- Supports connecting to multiple MCP servers simultaneously, managing multiple MCP servers via `json` files.
- Supports multiple transport methods: `STDIO|SSE|StreamableHTTP`.
- Provides a unified HTTP API interface for:
- Getting the tool list of all servers
- Calling tools on specific servers
- Getting the resource list of all servers
- Getting resources on specific servers
- Triggering the Host to actively update Server connections
## Project Structure
```bash
mcp-host-use/
├── src/ # Source code directory
│ ├── main.ts # Main entry file
│ ├── host.ts # MCP connection manager
│ ├── client.ts # MCP client implementation
│ ├── server.ts # HTTP server implementation
│ ├── types.ts # Type definitions
│ └── utils.ts # Utility functions
```
## Environment Requirements
- **Connecting to STDIO MCP Server requires a system environment with `npx` or `uvx`.**
- `npx` depends on Nodejs (>=18)
- `uvx` depends on Python (uv)
## Usage
### 1. Using the `npm` package, no local build required (Recommended)
`npx mcp-host-use`
### 2. Local build, clone this repository `git clone https://github.com/liujilongObject/mcp-host-use.git`
#### Install dependencies
- `npm install`
#### Development mode
- `npm run dev`
#### Production mode
- `npm run build`
- Use in production environment
- Using a custom Node.js environment: `production_node.exe dist/index.js`
- Using the host's Node.js environment: `node dist/index.js`
## Servers Configuration File
`mcp-host-use` will read the `mcp_servers.config.json` file in the **current working directory**. The file format is as follows:
```json
{
"mcp_servers": [
{
"enabled": true, // Whether to enable the server
"type": "stdio", // 'stdio' | 'sse' | 'streamableHttp'
"server_name": "server-puppeteer", // Custom name
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-puppeteer"
]
},
{
"enabled": true,
"type": "sse",
"server_name": "server-everything-sse",
"sse_url": "http://localhost:3001/sse"
},
{
"enabled": true,
"type": "stdio",
"server_name": "github",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": { // Supports configuring environment variables
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
]
}
```
## Notes
- The server runs on port 17925 by default.
- Ensure the server information in the configuration file is correct.
- For STDIO transport, ensure the following commands are executable:
- `npx`
- `uvx`
- For SSE|StreamableHTTP transport, ensure the URL is accessible.
## API Endpoints
## Tools
### 1. Get All Tool List
```bash
GET http://localhost:17925/api/tools
```
#### Response
```json
{
"code": 0,
"data": [
{
"server_name": "Server1",
"tools": [
{
"name": "Tool Name",
"description": "Tool Description",
"inputSchema": { ... }
}
]
}
]
}
```
### 2. Call Tool
```bash
POST http://localhost:17925/api/tools/toolCall
Content-Type: application/json
{
"server_name": "Server Name",
"tool_name": "Tool Name",
"tool_args": { ... }
}
```
#### Response
```json
{
"code": 0,
"data": {
"result": "Tool Execution Result"
}
}
```
## Resources
### 1. Get All Resource List
```bash
GET http://localhost:17925/api/resources
```
#### Response
```json
{
"code": 0,
"data": [
{
"server_name": "Server1",
"resources": [
{
"uri": "Resource URI",
"mimeType": "Resource Type",
"name": "Resource Name"
}
]
}
]
}
```
### 2. Read Specific Resource
```bash
POST http://localhost:17925/api/resources/read
Content-Type: application/json
{
"server_name": "Server Name",
"resource_uri": "Resource URI"
}
```
#### Response
```json
{
"code": 0,
"data": [
{
"mimeType": "Resource Type",
"text": "text type resource",
"blob": "blob type resource"
}
]
}
```
## Connections
### 1. Update Server Connection
> **After calling this API, the Host will actively read the configuration file and create/restart/delete Server connections based on the updated configuration. No need to restart the Host service, continuing to call APIs like `/api/tools` can get the updated Server information.**
```bash
POST http://localhost:17925/api/connections/update
Content-Type: application/json
```
#### Response
```json
{"code":0,"message":"Successfully updated server connection"}
```
## License
MIT
