Content
# Tool List
[](https://opensource.org/licenses/MIT)
A server based on [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), which encapsulates the `web_search` API of MiMo as a standard MCP tool, allowing AI assistants like Claude Code to perform real-time web searches.
## Features
- 🔍 **Real-time Web Search** - Get the latest web information
- 📊 **Structured Results** - Return title, URL, summary, and source citation
- 🌍 **Location-aware Search** - Support localized search by country/region/city
- 🔄 **Automatic Retry** - Built-in retry mechanism and timeout control
- 📝 **Detailed Logs** - Control log level through DEBUG environment variable
- 🛡️ **Type Safety** - Complete TypeScript type definitions
## Prerequisites
- Node.js >= 20.0.0
- MiMo API Key (obtained from [MiMo Platform](https://mimo.xiaomi.com))
## Get Source Code
```bash
git clone https://github.com/your-username/mimo-web-search-mcp.git
cd mimo-web-search-mcp
npm install
npm run build
```
## Configuration
### Claude Code Configuration
Edit `~/.claude.json` file (Windows users: `%USERPROFILE%\.claude.json`):
```json
{
"mcpServers": {
"mimo-web-search": {
"type": "stdio",
"command": "node",
"args": ["<project-path>/dist/index.js"],
"env": {
"MIMO_API_KEY": "your-api-key-here",
"MIMO_BASE_URL": "https://api.xiaomimimo.com/v1"
}
}
}
}
```
Replace `<project-path>` with the actual path, e.g.:
- Windows: `D:/CodeLocal/mimo-web-search-mcp/dist/index.js`
- macOS/Linux: `/home/user/mimo-web-search-mcp/dist/index.js`
### Environment Variables
| Variable | Required | Description | Default Value |
| --- | --- | --- | --- |
| `MIMO_API_KEY` | Yes | MiMo API Key | - |
| `MIMO_BASE_URL` | No | API base URL | `https://api.xiaomimimo.com/v1` |
| `MIMO_MODEL` | No | Model name | `mimo-v2.5-pro` |
| `REQUEST_TIMEOUT` | No | Request timeout (ms) | `60000` |
| `MAX_COMPLETION_TOKENS` | No | Max generated tokens | `1024` |
| `TEMPERATURE` | No | Sampling temperature (0-2) | `0.3` |
| `TOP_P` | No | Nucleus sampling probability (0-1) | `0.95` |
| `MIMO_STREAM` | No | Enable streaming response | `false` |
| `MIMO_THINKING` | No | Enable thinking mode | `false` |
| `DEBUG` | No | Log level: `0`=error (default), `1`=info, `2`=debug; or namespace pattern `mimo*` etc. | `0` |
| `MAX_RETRIES` | No | Max retries | `2` |
| `RETRY_DELAY` | No | Retry delay base (ms) | `1000` |
| `MAX_CONTENT_LENGTH` | No | Max response content length | `100000` |
| `MAX_CONCURRENT` | No | Max concurrent requests | `10` |
| `DEFAULT_MAX_KEYWORD` | No | Default max keywords | `3` |
| `DEFAULT_LIMIT` | No | Default return results | `5` |
| `MAX_QUERY_LENGTH` | No | Max query length | `10000` |
## Development
### Install Dependencies
```bash
npm install
```
### Development Mode (Hot Reload)
```bash
npm run dev
```
### Compile TypeScript
```bash
npm run build
```
### Type Checking
```bash
npm run typecheck
```
### Code Linting
```bash
npm run lint
```
### Testing
```bash
# Run all tests (vitest, required before submission)
npm test
# Watch mode
npm run test:watch
# With coverage
npm run test:coverage
# Complete pre-commit check (type checking + ESLint + tests)
npm run precommit
```
## Usage
After configuration, Claude Code will automatically recognize and use the `mimo_web_search` tool.
### Using in Claude Code
Directly ask questions, and Claude will automatically call the search tool:
```
User: What's the weather like in Beijing today?
Claude: [Automatically call mimo_web_search to query Beijing weather]
```
### Tool Parameters
| Parameter | Type | Default Value | Description |
| --- | --- | --- | --- |
| `query` | string | Required | Search query (max 10000 characters) |
| `max_keyword` | int (1-50) | 3 | Max concurrent keywords (each ¥0.025) |
| `limit` | int (1-50) | 5 | Return results |
| `force_search` | boolean | true | Force search even if model thinks it knows the answer |
| `country` | string | Optional | Country (e.g., 'China') |
| `region` | string | Optional | Region/province (e.g., 'Hubei') |
| `city` | string | Optional | City (e.g., 'Wuhan') |
### Example Response
```
According to search results, Beijing's weather today is sunny, with a temperature of 25°C...
--- Sources ---
- [Beijing Weather Forecast](https://weather.com/beijing) — China Weather Network (2025-01-15)
- [Beijing Real-time Weather](https://www.weather.com.cn) — China Meteorological Administration (2025-01-15)
```
## Project Structure
```
mimo-web-search-mcp/
├── src/
│ ├── index.ts # MCP server main entry
│ ├── config.ts # Configuration management (environment variable loading and validation)
│ ├── logger.ts # Logging tool
│ └── types.ts # Zod schema + TypeScript type definitions
├── tests/
│ ├── config.test.ts # Configuration module tests
│ ├── logger.test.ts # Logging module tests
│ └── search.test.ts # Search logic tests (mock fetch)
├── dist/ # Compilation output (automatically ignored)
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── eslint.config.js
├── CLAUDE.md
├── README.md
└── LICENSE
```
## Security Notes
This MCP server only acts as a proxy layer for MiMo search API, without filtering prompt injection in return content. It is the responsibility of the client (Claude Code, etc.) to defend against prompt injection.
## Error Handling
The server will handle various error situations:
- **Authentication Error** (401/403): Prompt to check API key
- **Rate Limiting** (429): Prompt to retry later
- **Server Error** (5xx): Prompt service temporarily unavailable
- **Timeout Error**: Prompt service response slow
- **Network Error**: Prompt to check network connection
## License
MIT License - see [LICENSE](LICENSE) file
## Contribution
Feel free to submit issues and pull requests!
## Acknowledgements
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MiMo API](https://mimo.xiaomi.com)
- [Claude Code](https://docs.anthropic.com/claude-code)
