npm package: @hu14/searxng-mcp
Description: MCP server for SearXNG search API integration
Latest version: 1.0.1

# SearXNG MCP Server

A Model Context Protocol (MCP) server that enables LLMs to search the web using SearXNG meta search engine.

## Features

- **Web Search**: Search across multiple search engines through SearXNG
- **Multiple Categories**: Support for general, images, videos, news, maps, music, IT, science, files, and social media
- **Time Filtering**: Filter results by day, week, month, or year
- **Language Support**: Search in specific languages or auto-detect
- **Safe Search**: Configurable safe search levels
- **Autocomplete**: Get search suggestions as you type
- **Pagination**: Navigate through large result sets
- **Multiple Formats**: JSON for programmatic use, Markdown for readability
- **Dual Transport**: Supports both stdio (for MCP) and HTTP modes

## Installation

```bash
# Install from npm
npm install -g @hu14/searxng-mcp

# Or run with npx
npx @hu14/searxng-mcp
```

### From Source

```bash
# Clone or download this repository
cd searxng-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

## Requirements

- Node.js >= 18
- A running SearXNG instance (self-hosted or public)

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SEARXNG_URL` | URL of your SearXNG instance | `http://localhost:8080` |
| `TRANSPORT` | Transport mode: `stdio` or `http` | `stdio` |
| `PORT` | HTTP server port (when using http transport) | `3000` |

### Setting up SearXNG

You need a running SearXNG instance. Options:

1. **Self-hosted**: [Install SearXNG](https://docs.searxng.org/admin/installation.html) locally
2. **Public instance**: Use a public SearXNG instance (check [searx.space](https://searx.space))

For JSON API access, ensure your SearXNG instance has `json` output format enabled in `settings.yml`:

```yaml
search:
  formats:
    - html
    - json
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json` or `~/.claude.json`):

```json
{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "@hu14/searxng-mcp"],
      "env": {
        "SEARXNG_URL": "https://your-searxng-instance.com"
      }
    }
  }
}
```

Or for local development:

```json
{
  "mcpServers": {
    "searxng": {
      "command": "node",
      "args": ["/path/to/searxng-mcp/dist/index.js"],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}
```

### With MCP Inspector (for testing)

```bash
npx @modelcontextprotocol/inspector npx -y @hu14/searxng-mcp
```

### As HTTP Server

```bash
# Using npx
SEARXNG_URL=https://searx.example.com TRANSPORT=http PORT=3000 npx @hu14/searxng-mcp

# Or from source
TRANSPORT=http PORT=3000 node dist/index.js
```

## Available Tools

### `searxng_search`

Search the web using SearXNG.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search query (1-500 characters) |
| `category` | string | No | Search category: `general`, `images`, `videos`, `news`, `maps`, `music`, `it`, `science`, `files`, `social_media` |
| `language` | string | No | Language code (e.g., `en`, `zh`, `de`) or `auto` |
| `time_range` | string | No | Time filter: `day`, `week`, `month`, `year` |
| `safesearch` | number | No | Safe search level: 0 (off), 1 (moderate), 2 (strict) |
| `limit` | number | No | Max results to return (1-100, default: 20) |
| `offset` | number | No | Skip N results for pagination (default: 0) |
| `response_format` | string | No | Output format: `markdown` or `json` |

**Examples:**

```json
{
  "query": "TypeScript best practices",
  "category": "general",
  "language": "en",
  "limit": 10
}
```

```json
{
  "query": "artificial intelligence",
  "category": "news",
  "time_range": "week"
}
```

### `searxng_autocomplete`

Get search suggestions for a partial query.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Partial search query (1-200 characters) |
| `language` | string | No | Language code or `auto` |
| `response_format` | string | No | Output format: `markdown` or `json` |

## Response Format

### Markdown Format (Default)

Human-readable formatted output with headers, links, and metadata.

### JSON Format

Structured data for programmatic processing:

```json
{
  "total": 150,
  "count": 20,
  "offset": 0,
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "content": "Result description...",
      "engine": "google",
      "publishedDate": "2024-01-15"
    }
  ],
  "suggestions": ["related query 1", "related query 2"],
  "has_more": true,
  "next_offset": 20
}
```

## Development

```bash
# Clone the repository
git clone <repository-url>
cd searxng-mcp

# Install dependencies
npm install

# Development with auto-reload
npm run dev

# Build
npm run build

# Clean build artifacts
npm run clean
```

## Changelog

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

## License

MIT