# LangSearch MCP Server
A Model Context Protocol (MCP) server that provides web search and semantic reranking capabilities using the [LangSearch API](https://docs.langsearch.com/).
## Features
- **Web Search**: Search billions of web documents with AI-optimized results
- Full page summaries
- Freshness filtering (day, week, month)
- Customizable result count
- Machine-readable structured output
- **Semantic Reranking**: Improve search accuracy with deep semantic understanding
- Reorder documents by semantic relevance
- Relevance scores (0-1 scale)
- Better than traditional keyword/vector search
- Top-N filtering
## Installation
### Prerequisites
- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- LangSearch API key from [https://langsearch.com](https://langsearch.com)
### Setup
1. Clone or navigate to the repository:
```bash
cd langsearch-mcp-python
```
2. Install dependencies:
```bash
uv sync
```
3. Configure your API key:
```bash
cp .env.example .env
# Edit .env and add your LANGSEARCH_API_KEY
```
## Usage
### Testing with MCP Inspector
Test the server interactively:
```bash
uv run mcp dev main.py
```
This opens the MCP Inspector where you can:
- Browse available tools
- Test tool invocations
- View structured responses
### Installing to Claude Desktop
Install the server for use with Claude Desktop:
```bash
uv run mcp install main.py
```
Follow the prompts to configure the installation.
### Manual Installation in Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"langsearch": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/langsearch-mcp-python",
"run",
"main.py"
],
"env": {
"LANGSEARCH_API_KEY": "your_api_key_here"
}
}
}
}
```
### Running as HTTP Server
For remote access, run as an HTTP server:
```python
# In main.py, change the last line to:
if __name__ == "__main__":
mcp.run(transport="streamable-http")
```
Then run:
```bash
uv run main.py
```
Access at `http://localhost:8000/mcp`
## Tools
### web_search
Search the web for information across billions of documents.
**Parameters:**
- `query` (string, required): Search query
- `count` (integer, default=10): Number of results (1-50)
- `summary` (boolean, default=true): Include full page summaries
- `freshness` (string, default="noLimit"): Filter by freshness
- `"noLimit"`: All results
- `"day"`: Last 24 hours
- `"week"`: Last 7 days
- `"month"`: Last 30 days
**Returns:** Structured data with:
- Total result count
- Web pages with title, URL, snippet, summary
- Original query
**Example:**
```json
{
"query": "latest AI developments 2026",
"count": 5,
"summary": true,
"freshness": "week"
}
```
### semantic_rerank
Rerank documents based on semantic relevance to a query.
**Parameters:**
- `query` (string, required): Search query for ranking
- `documents` (array[string], required): List of document texts to rerank
- `top_n` (integer, optional): Return only top N results
- `model` (string, default="langsearch-reranker-v1"): Reranker model
**Returns:** Structured data with:
- Reranked documents with indices
- Relevance scores (0-1, higher = more relevant)
- Model used
**Example:**
```json
{
"query": "machine learning algorithms",
"documents": [
"Deep learning is a subset of machine learning...",
"The history of neural networks dates back...",
"Random forests are ensemble learning methods..."
],
"top_n": 2
}
```
## Development
### Project Structure
```
langsearch-mcp-python/
├── main.py # MCP server implementation
├── pyproject.toml # Project dependencies
├── uv.lock # Locked dependencies
├── .env.example # Example environment variables
├── .gitignore # Git ignore rules
└── README.md # This file
```
### Running Tests
```bash
# Test with MCP Inspector
uv run mcp dev main.py
# Test individual tools
uv run python -c "
from main import web_search
import asyncio
result = asyncio.run(web_search('Python programming', count=3))
print(result)
"
```
### Error Handling
The server provides clear error messages for:
- Missing API key
- Invalid parameters
- API errors
- Network issues
Errors are returned as structured exceptions with descriptive messages.
## API Reference
For detailed API documentation, see:
- [Web Search API](https://docs.langsearch.com/api/web-search-api)
- [Semantic Rerank API](https://docs.langsearch.com/api/semantic-rerank-api)
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `LANGSEARCH_API_KEY` | Yes | Your LangSearch API key |
## License
MIT
## Support
For issues and questions:
- LangSearch API: [docs.langsearch.com](https://docs.langsearch.com/)
- MCP Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
## Contributing
Contributions are welcome! Please ensure:
- Type hints are used throughout
- Docstrings follow the existing format
- Error handling is comprehensive
- Tests pass with `uv run mcp dev`
