Content
# AI Search MCP Server
[](https://github.com/lianwusuoai/ai-search-mcp/blob/main/LICENSE)
A universal AI search MCP server that supports any AI model compatible with the OpenAI API format for online searching.
**High-performance Rust implementation, supporting true concurrent search.**
## Features
- ✅ Supports any OpenAI API compatible model
- ✅ Supports streaming and non-streaming responses
- ✅ Automatically filters AI thinking content
- ✅ **Automatic time injection**: Automatically injects the current time for each search
- ✅ **Multi-dimensional search**: Automatically splits complex queries into multiple sub-questions for parallel search
- ✅ **Intelligent retry mechanism**: Automatically retries failed requests
- ✅ **High-performance concurrency**: Based on Tokio asynchronous runtime
- ✅ **Zero-dependency deployment**: Single binary file
- ✅ Fully configurable (supports custom system prompts)
## Quick Start
### 1. Installation
**One-click installation (recommended)**:
```bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/lianwusuoai/ai-search-mcp/main/scripts/install.ps1 | iex
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/lianwusuoai/ai-search-mcp/main/scripts/install.sh | bash
```
**Manual installation**:
```bash
# Using pip
pip install ai-search-mcp
# Or using uvx (recommended)
uvx ai-search-mcp
```
### 2. Configuration
**Web UI configuration (recommended)**:
```bash
# Start configuration interface
ai-search-mcp --http --port 11000
# Open in browser
http://localhost:11000/config
```
**Configuration file** (`~/.ai-search-mcp/config.json`):
```json
{
"api_url": "http://localhost:10000",
"api_key": "your-api-key",
"search_model_id": "Grok",
"analysis_model_id": "MiniMax",
"timeout": 180,
"stream": true,
"filter_thinking": true,
"analysis_retry_count": 1,
"search_retry_count": 0,
"log_level": "INFO",
"max_query_plan": 10
}
```
### 3. Integration into MCP Client
#### Method 1: stdio mode (recommended, local use)
Edit configuration file (Kiro: `.kiro/settings/mcp.json` | Claude Desktop: `claude_desktop_config.json`):
```json
{
"mcpServers": {
"ai-search": {
"command": "uvx",
"args": ["ai-search-mcp"]
}
}
}
```
**Features**:
- Automatically starts process, no manual management needed
- Communicates through standard input/output
- Automatically exits when client closes
- Suitable for: IDE integration (Kiro, Claude Desktop, Cursor)
#### Method 2: HTTP mode (starts independent server)
```json
{
"mcpServers": {
"ai-search": {
"command": "ai-search-mcp",
"args": ["--http", "--port", "11000"]
}
}
}
```
**Features**:
- Starts independent HTTP server process
- Supports multiple client concurrent connections
- Requires manual management of process lifecycle
- Suitable for: temporary testing, development debugging
#### Method 3: SSE mode (connects to remote server)
**Prerequisites**: Need to start HTTP server (Docker or manual start)
```bash
# Docker start (recommended)
docker-compose up -d
# Or manual start
ai-search-mcp --http --port 11000
```
**Configuration**:
```json
{
"mcpServers": {
"ai-search": {
"url": "http://localhost:11000/sse?key=xinchen"
}
}
}
```
**Features**:
- Connects to already running remote server
- Pushes messages in real-time through SSE
- Server runs independently, supports multiple clients
- Suitable for: production environment, remote deployment, multiple clients sharing
**Comparison**:
| Feature | stdio mode | HTTP mode | SSE mode |
|------|-----------|----------|---------|
| Startup method | Automatically starts process | Automatically starts process | Connects to remote server |
| Server management | Automatic management | Manual management | Independent operation |
| Multiple clients | ❌ | ✅ | ✅ |
| Remote access | ❌ | ❌ | ✅ |
| Applicable scenario | Local IDE | Development testing | Production environment |
## Operating Mode Description
### stdio mode (default)
- Started by MCP client as needed, runs as subprocess
- Suitable for IDE integration (Kiro, Claude Desktop, Cursor, etc.)
- Automatically exits when client closes
### HTTP mode
**Docker deployment (recommended)**:
```bash
# Quick start
.\docker-start.ps1 # Windows
./docker-start.sh # Linux/macOS
# Or manual start
docker-compose up -d
```
**Manual start**:
```bash
ai-search-mcp --http --port 11000
```
**Comparison**:
| Feature | stdio mode | HTTP (Docker) | HTTP (manual) |
|------|-----------|--------------|------------|
| Startup method | Automatic | One-time setup | Manual each time |
| Automatic restart | ✅ | ✅ | ❌ |
| Multiple clients | ❌ | ✅ | ✅ |
| Applicable scenario | IDE integration | Production environment | Temporary testing |
## Configuration Description
### Core configuration
| Variable | Required | Default value | Description |
|------|------|--------|------|
| `api_url` | ✅ | - | AI API address |
| `api_key` | ✅ | - | API key |
| `search_model_id` | ✅ | - | Search query generation model ID |
| `analysis_model_id` | ❌ | Uses `search_model_id` if not set | Query splitting model ID |
| `timeout` | ❌ | `180` | Timeout time (seconds) |
| `stream` | ❌ | `true` | Enables streaming response |
| `filter_thinking` | ❌ | `true` | Filters thinking content |
| `analysis_retry_count` | ❌ | `1` | Analysis retry count |
| `search_retry_count` | ❌ | `0` | Search retry count |
| `max_query_plan` | ❌ | `10` | Complex query splitting dimension count (recommended 1~1000) |
### Model usage logic
System determines which models to use based on `max_query_plan` and `analysis_model_id` configuration:
```mermaid
graph TD
A[User query] --> B{max_query_plan = 1?}
B -->|yes| C[Single query mode]
B -->|no| D[Multi-dimensional search mode]
C --> E[Use search model]
E --> F[Use search system prompt]
F --> G[Return search results]
D --> H{Is analysis model configured?}
H -->|yes| I[Use analysis model to split]
H -->|no| J[Use search model to split]
I --> K[Use query splitting prompt]
J --> K
K --> L[Generate multiple sub-queries]
L --> M[Execute sub-queries concurrently]
M --> N[Use search model]
N --> F
F --> O[Return results for each sub-query]
O --> P[AI merges all results]
P --> Q[Return complete answer]
```
**Key points**:
- `max_query_plan = 1`: No query splitting, no analysis model used
- `max_query_plan > 1` + no analysis model: Uses search model to split queries
- `max_query_plan > 1` + analysis model configured: Uses analysis model to split queries
**Model configuration suggestions**:
Single model configuration:
"search_model_id": "Grok" Single online search model
Dual model configuration:
"search_model_id": "Grok" Use high-concurrency channel for online search model
"analysis_model_id": "MiniMax" Recommended non-thinking model for speed improvement
## Prompt Configuration
**Recommended method**: Configure through Web UI (`http://localhost:11000`)
**Configuration file method**:
```json
{
"system_prompt": "Custom search system prompt (must retain {current_time} placeholder)",
"split_prompt": "Custom query splitting prompt"
}
```
For detailed instructions, see [Prompt Configuration Instructions](docs/提示词配置说明.md)
## Tool Description
### `web_search` - Web search
**Input**: `{"query": "search content"}`
**Multi-dimensional search** (controlled by `max_query_plan`):
- `= 1`: Directly returns search results
- `> 1`: First call returns splitting requirements, AI needs to split into N sub-questions for parallel search
## Multi-dimensional Search Example
### Simple query (max_query_plan = 1)
User: What is Python?
→ AI call: `web_search("What is Python?")`
→ MCP returns: Directly returns search results
### Complex query (max_query_plan = 10)
User: Spring Festival Beijing to Shanghai high-speed rail ticket price
→ AI first call: `web_search("Spring Festival Beijing to Shanghai high-speed rail ticket price")`
→ MCP returns: Splitting requirements (prompts to split into multiple sub-questions)
→ AI parallel calls:
```
web_search("[SUB_QUERY] Spring Festival Beijing to Shanghai direct high-speed rail ticket price")
web_search("[SUB_QUERY] Beijing to Shanghai transfer plan ticket price comparison")
web_search("[SUB_QUERY] Beijing surrounding stations to Shanghai buy long ride short strategy")
```
→ MCP returns: Search results for each sub-query
→ AI integrates: Automatically integrates results, returns complete answer
**Performance improvement**: Rust version concurrently executes sub-queries, total time approximately 1 second (Python sequential execution approximately 3 seconds)
## Frequently Asked Questions
### How to update?
```bash
# Upgrade Python package
pip install --upgrade ai-search-mcp
# Automatically detect and update Docker (if used)
ai-search-mcp-deploy
```
### Docker container cannot start?
```bash
# View logs
docker-compose logs
# Rebuild
docker-compose down
docker-compose up -d --build
```
### Version inconsistency?
```bash
# View Python package version (MCP server version)
ai-search-mcp --version
# View Docker container version (HTTP server version)
curl http://localhost:11000/health
# Force redeployment (synchronize version)
ai-search-mcp-deploy --force
```
## License
MIT License
## Links
- [GitHub](https://github.com/lianwusuoai/ai-search-mcp)
- [Issue feedback](https://github.com/lianwusuoai/ai-search-mcp/issues)
