# SearXNG MCP Server

A bridge to use SearXNG as an MCP server from Claude Code.

**[日本語版 README はこちら](README.ja.md)**

## Features

- **searxng_search**: Web search with multiple engines
- **searxng_images**: Image search
- **searxng_news**: News search

## Prerequisites

1. SearXNG instance running with JSON format enabled

   **Important**: SearXNG's default configuration only allows HTML format. To use this MCP server, you must enable JSON format by mounting a custom configuration file.

   First, create your configuration file from the example:

   ```bash
   cp searxng-config/settings.yml.example searxng-config/settings.yml
   # Edit settings.yml to set your own secret_key
   ```

   Then start SearXNG with the configuration:

   ```bash
   # Using Docker (recommended)
   docker run -d \
     -p 8080:8080 \
     -v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
     -e SEARXNG_BASE_URL=http://localhost:8080/ \
     searxng/searxng

   # Or install locally
   # See: https://docs.searxng.org/admin/installation.html
   ```

   The `searxng-config/settings.yml.example` file includes the necessary configuration to enable JSON format:

   ```yaml
   use_default_settings: true

   search:
     formats:
       - html
       - json

   server:
     secret_key: "your-secret-key-here"
     limiter: false
     image_proxy: true
   ```

2. Verify SearXNG is running with JSON format enabled

   ```bash
   curl "http://localhost:8080/search?q=test&format=json"
   ```

   If you get a `403 Forbidden` error, the JSON format is not enabled. Make sure you mounted the configuration file correctly.

## Installation

```bash
cd searxng-mcp-server
npm install
npm run build
```

## Claude Code Configuration

### Method 1: Using CLI (Recommended)

```bash
# Add to local scope (current project)
claude mcp add --transport stdio searxng -- node /path/to/searxng-mcp-server/dist/index.js

# Add to user scope (all projects)
claude mcp add --transport stdio searxng --scope user -- node /path/to/searxng-mcp-server/dist/index.js
```

To add environment variables:

```bash
claude mcp add --transport stdio searxng \
  --env SEARXNG_BASE_URL=http://localhost:8080 \
  -- node /path/to/searxng-mcp-server/dist/index.js
```

### Method 2: Manual Configuration

**Project scope** (`.mcp.json` in project root):

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

**User scope** (`~/.claude.json`):

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

### Verify Installation

```bash
# List configured MCP servers
claude mcp list

# Inside Claude Code
/mcp
```

## Auto-approve Tool Calls (Optional)

By default, Claude Code asks for confirmation each time a SearXNG tool is called. To skip confirmations, add the following to `~/.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "mcp__searxng__searxng_search",
      "mcp__searxng__searxng_images",
      "mcp__searxng__searxng_news"
    ]
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SEARXNG_BASE_URL` | `http://localhost:8080` | SearXNG server URL |

## Usage Examples

From Claude Code:

### Web Search

```text
Search for "Rust programming language features" using SearXNG
```

### Image Search

```text
Find images of "Mount Fuji" using SearXNG
```

### News Search

```text
Get latest news about "AI developments" using SearXNG
```

## Troubleshooting

### 403 Forbidden error with JSON format

If you get a `403 Forbidden` error when using `format=json`, the JSON format is not enabled in your SearXNG instance. Make sure you:

1. Mount the configuration file when starting Docker:

   ```bash
   docker run -d \
     -p 8080:8080 \
     -v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
     -e SEARXNG_BASE_URL=http://localhost:8080/ \
     searxng/searxng
   ```

2. Verify the configuration includes JSON format:

   ```bash
   docker exec <container_id> grep -A 3 "formats" /etc/searxng/settings.yml
   ```

### Cannot connect to SearXNG

```bash
# Check if SearXNG is running
curl "http://localhost:8080/search?q=test&format=json"

# If not running (Docker) - make sure to mount the config file
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
  -e SEARXNG_BASE_URL=http://localhost:8080/ \
  searxng/searxng
```

### No results returned

SearXNG aggregates results from multiple search engines. If no results are returned:

1. Check if your SearXNG instance has engines enabled
2. Try specifying engines: `engines: "google,bing,duckduckgo"`
3. Check SearXNG logs for errors

### MCP server not showing up

```bash
# Verify server is registered
claude mcp list

# Check server health
claude mcp get searxng
```

## License

MIT