# 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
