# SearXNG MCP Server

A Model Context Protocol (MCP) server that integrates with [SearXNG](https://github.com/searxng/searxng), providing powerful web search capabilities to MCP clients like Claude Desktop, Cline, and other MCP-compatible applications.

## Features

- 🔍 **Web Search**: Search across multiple search engines aggregated by SearXNG
- 🎯 **Category Filtering**: Filter by categories (general, images, videos, news, etc.)
- 🌐 **Multi-Engine**: Query specific search engines or use them all
- 🌍 **Localization**: Search in different languages
- ⏰ **Time Filtering**: Filter results by time range (day, month, year)
- 🛡️ **Safe Search**: Configurable safe search levels
- 💡 **Autocomplete**: Get search suggestions for query completion
- 🔧 **Configuration Access**: Query SearXNG instance capabilities
- 🏥 **Health Monitoring**: Check instance health status

## Prerequisites

- Python 3.10 or higher
- A running SearXNG instance (local or remote)
- An MCP client (e.g., Claude Desktop, Cline)

## Installation

### From Source

1. Clone the repository:
```bash
git clone https://github.com/martinchen448/searxng-mcp-server.git
cd searxng-mcp-server
```

2. Install the package:
```bash
pip install -e .
```

### From PyPI (coming soon)

```bash
pip install searxng-mcp-server
```

## Configuration

### For 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`

**For Local Instance (Recommended):**
```json
{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080/",
        "SEARXNG_VERIFY_SSL": "false"
      }
    }
  }
}
```

**For Public Instance:**
```json
{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "https://searx.be",
        "SEARXNG_VERIFY_SSL": "true"
      }
    }
  }
}
```

### For Cline (VSCode Extension)

Add to your MCP settings file:

**Path**: `<User Directory>/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`

**For Local Instance (Recommended):**
```json
{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080/",
        "SEARXNG_VERIFY_SSL": "false"
      }
    }
  }
}
```

**For Public Instance:**
```json
{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "https://searx.be",
        "SEARXNG_VERIFY_SSL": "true"
      }
    }
  }
}
```

### Environment Variables

- `SEARXNG_BASE_URL` (required): Base URL of your SearXNG instance
  - Example: `https://search.example.com` or `http://localhost:8888`
- `SEARXNG_VERIFY_SSL` (optional): Whether to verify SSL certificates
  - Default: `true`
  - Set to `false` for self-signed certificates or local development

## Testing with MCP Inspector

Before using with Claude Desktop or Cline, test your server with the MCP Inspector.

### Quick Start

Use the provided convenience scripts:

**Windows (Command Prompt):**
```cmd
run-inspector.bat
```

**Windows (PowerShell):**
```powershell
.\run-inspector.ps1
```

**Linux/macOS:**
```bash
chmod +x run-inspector.sh
./run-inspector.sh
```

**Or run directly:**
```bash
# Set environment variable first
export SEARXNG_BASE_URL=https://searx.be  # Linux/macOS
set SEARXNG_BASE_URL=https://searx.be     # Windows CMD
$env:SEARXNG_BASE_URL="https://searx.be"  # Windows PowerShell

# Then run inspector
npx @modelcontextprotocol/inspector python -m searxng_mcp_server
```

The Inspector will open in your browser (typically http://localhost:5173) where you can:
- Test all tools interactively
- View real-time request/response logs
- Inspect resources
- Debug connection issues

For detailed testing instructions, see [Testing with MCP Inspector](docs/TESTING_WITH_INSPECTOR.md).

## Setting Up SearXNG

If you don't have a SearXNG instance, you can:

### Use a Public Instance

Find public instances at: https://searx.space/

Example public instances:
- https://searx.be
- https://searx.tiekoetter.com
- https://search.sapti.me

**Important Notes**:
- Public instances may have rate limits or restrictions
- Some public instances block automated requests (HTTP 403 errors)
- For reliable operation, consider running your own instance
- If you encounter 403 errors, try a different public instance or set up a local instance

### Run Your Own Instance

Using Docker (recommended):

```bash
docker pull searxng/searxng
docker run -d -p 8888:8080 \
  -v "${PWD}/searxng:/etc/searxng" \
  -e "BASE_URL=http://localhost:8888/" \
  -e "INSTANCE_NAME=my-instance" \
  searxng/searxng
```

See the [SearXNG documentation](https://docs.searxng.org/) for more deployment options.

## Available Tools

### 1. search

Perform web searches across multiple search engines.

**Parameters:**
- `query` (required): Search query string
- `categories` (optional): Array of categories (e.g., `["general", "images", "news"]`)
- `engines` (optional): Array of specific engines (e.g., `["google", "bing"]`)
- `language` (optional): Language code (default: `"en"`)
- `page` (optional): Page number for pagination (default: 1)
- `time_range` (optional): Filter by time ("day", "month", "year")
- `safesearch` (optional): Safe search level (0=off, 1=moderate, 2=strict)

**Example:**
```json
{
  "query": "Python async programming",
  "categories": ["general"],
  "language": "en",
  "time_range": "year",
  "safesearch": 0
}
```

### 2. get_suggestions

Get autocomplete suggestions for a query prefix.

**Parameters:**
- `query` (required): Query prefix
- `language` (optional): Language code (default: `"en"`)

**Example:**
```json
{
  "query": "machine learn",
  "language": "en"
}
```

### 3. health_check

Check if the SearXNG instance is accessible and healthy.

**Parameters:** None

### 4. get_config

Get the configuration and capabilities of the SearXNG instance.

**Parameters:** None

**Returns information about:**
- Available search engines
- Enabled categories
- Supported languages
- Active plugins
- Instance settings

## Available Resources

### searxng://config

Access to the SearXNG instance configuration as a persistent resource.

### searxng://health

Health status of the SearXNG instance as a persistent resource.

## Usage Examples

### Example 1: Basic Web Search

Ask your MCP client:
```
Search for "best practices for Python async programming"
```

### Example 2: Image Search

Ask your MCP client:
```
Search for images of "northern lights" from the past month
```

The server will use:
```json
{
  "query": "northern lights",
  "categories": ["images"],
  "time_range": "month"
}
```

### Example 3: News Search

Ask your MCP client:
```
Find recent news about artificial intelligence
```

The server will use:
```json
{
  "query": "artificial intelligence",
  "categories": ["news"],
  "time_range": "day"
}
```

### Example 4: Get Search Suggestions

Ask your MCP client:
```
Get search suggestions for "climate"
```

## Search Categories

Available categories in SearXNG:
- `general` - General web search
- `images` - Image search
- `videos` - Video search
- `news` - News articles
- `music` - Music search
- `files` - File search
- `social media` - Social media posts
- `science` - Scientific articles
- `it` - IT/Programming resources
- `map` - Maps and locations

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/martinchen448/searxng-mcp-server.git
cd searxng-mcp-server

# Install with dev dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
# Format code with black
black src tests

# Lint with ruff
ruff check src tests

# Type checking with mypy
mypy src
```

### Project Structure

```
searxng-mcp-server/
├── src/
│   └── searxng_mcp_server/
│       ├── __init__.py
│       ├── server.py      # MCP server implementation
│       └── client.py      # SearXNG API client
├── tests/
│   ├── test_server.py
│   └── test_client.py
├── pyproject.toml
└── README.md
```

## Troubleshooting

### Connection Issues

If you encounter connection errors:

1. **Verify the SearXNG URL**: Ensure `SEARXNG_BASE_URL` is correct and accessible
2. **Check SSL certificates**: For self-signed certificates, set `SEARXNG_VERIFY_SSL=false`
3. **Test the instance**: Visit the URL in your browser to ensure it's running
4. **Check firewall**: Ensure no firewall is blocking the connection

### SSL Certificate Errors

For self-signed certificates or local development:

```json
{
  "env": {
    "SEARXNG_BASE_URL": "http://localhost:8888",
    "SEARXNG_VERIFY_SSL": "false"
  }
}
```

### No Results

If searches return no results:

1. **Check instance configuration**: Use the `get_config` tool to see available engines
2. **Verify engines are enabled**: Some instances may have limited engines
3. **Try different categories**: Some categories may not be available
4. **Check instance logs**: Review SearXNG logs for errors

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [SearXNG](https://github.com/searxng/searxng) - The privacy-respecting metasearch engine
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [Anthropic](https://www.anthropic.com/) - For developing the MCP standard

## Related Projects

- [SearXNG](https://github.com/searxng/searxng) - Privacy-respecting metasearch engine
- [MCP Specification](https://github.com/modelcontextprotocol/specification) - MCP protocol documentation
- [Claude Desktop](https://claude.ai/download) - Desktop application with MCP support

## Support

- 🐛 [Report bugs](https://github.com/martinchen448/searxng-mcp-server/issues)
- 💡 [Request features](https://github.com/martinchen448/searxng-mcp-server/issues)
- 📖 [Documentation](https://github.com/martinchen448/searxng-mcp-server/wiki)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.