ninickname/searxng-mcp-server

SearXNG MCP Server

A Spring Boot-based MCP (Model Context Protocol) server that provides local web search capabilities using SearXNG search engine.

🌟 Features

• 🔒 No API Keys Required - Completely local setup with no external dependencies
• 🛡️ Privacy-First - All searches run locally through SearXNG
• 🔌 MCP Protocol Compatible - Works with Claude Desktop and other MCP clients
• 🐳 Docker Ready - Easy deployment with Docker Compose

🚀 Quick Start

Prerequisites

• Java 21+
• Maven 3.6+
• Docker & Docker Compose

1. Build and Start

# Build the application
mvn clean package

# Start services (SearXNG + MCP Server)
docker-compose up -d

2. Verify Setup

# Check SearXNG (should return HTML page)
curl http://localhost:9100

# Check MCP Server (should return {"status":"UP"})
curl http://localhost:9101/mcp/health

3. Test with MCP Inspector 🎯 (Optional)

The MCP Inspector is an optional tool included for convenience to quickly verify the MCP server status and explore available tools without manual curl commands.

1. Open in your browser: http://localhost:6274
2. Configure connection:
   • URL: http://mcp-server:9101/mcp
   • Transport Type: Streamable HTTP
   • Connection Type: Via Proxy
3. Click "List Tools" to see available tools
4. Try the web_search tool with a query!

💡 Note: The MCP Inspector is optional but helpful for getting faster indication of server status and features. For more details, visit: https://github.com/modelcontextprotocol/inspector

4. Connect MCP Clients

The server uses STREAMABLE (SSE) protocol. Configure your MCP client accordingly:

Note: This server uses Spring AI MCP with SSE transport. Standard HTTP MCP clients may need additional configuration or use SSE-compatible endpoints.

🔧 Available MCP Tools

web_search

Search the web using your local SearXNG instance.

Parameters:

• query (string, required) - The search query
• page (integer, optional) - Page number for pagination (default: 1)

Returns:

• query - The original search query
• results - Array of search results with:
  • url - Result URL
  • title - Result title
  • content - Result description/snippet
  • engine - Search engine source
  • score - Relevance score
• suggestions - Array of search suggestions

Example:

curl -X POST http://localhost:9101/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "web_search",
      "arguments": {
        "query": "spring boot tutorial",
        "page": 1
      }
    },
    "id": "1"
  }'

🏗️ Architecture

┌─────────────────┐         ┌──────────────────────────┐
│   MCP Client    │ ------> │  MCP Server              │
│  (e.g. Claude)  │  HTTP   │  (Port 9101)             │
└─────────────────┘         │  Spring Boot + Spring AI │
                            └──────────────────────────┘
       ┌────────────────────────────┘
       │                            |
       v                            | http://searxng:8080
┌──────────────────────────┐        | (Docker network)
│  MCP Inspector           │        v
│  (Port 6274)             │ ┌──────────────────────────┐
│  Testing & Debug UI      │ │    SearXNG               │
└──────────────────────────┘ │    (Port 9100)           │
                             │    Local Search Engine   │
                             └──────────────────────────┘

Components

• MCP Server: Spring Boot application implementing MCP protocol using Spring AI MCP framework
  • Listens on 0.0.0.0:9101 inside container, mapped to host localhost:9101
  • Uses STREAMABLE (SSE) protocol for MCP communication
  • Communicates with SearXNG via Docker service name searxng:8080
• SearXNG: Local search engine for privacy-respecting web searches
  • Runs on port 9100 (host) mapped from container port 8080
• MCP Inspector (Optional): Web-based testing and debugging tool for quick status checks and feature exploration
  • UI available at http://localhost:6274
  • Proxy server on port 6277
  • Pre-configured to work with the MCP server
  • More info: https://github.com/modelcontextprotocol/inspector
• Docker Compose: Orchestrates all three services with proper networking

🛠️ Development

Running Tests

mvn test

Development Mode

# Run MCP server in development
mvn spring-boot:run

# Start only SearXNG for development
docker-compose up searxng -d

Stop Services

docker-compose down

📁 Project Structure

├── src/main/java/com/example/searxngmcp/
│   ├── SearXNGMcpServerApplication.java    # Main Spring Boot application
│   └── service/
│       └── WebSearchToolService.java       # @McpTool service with WebClient & response records
├── src/main/resources/
│   └── application.properties              # App configuration (ports, SearXNG URL)
├── docker-compose.yml                      # Service orchestration
├── Dockerfile                              # Multi-stage Docker build
├── CLAUDE.md                               # Claude Code development guide
└── README.md                               # This file

🔧 Technical Details

Dependencies

Core Maven dependencies:

• Spring Boot 3.2.0 (spring-boot-starter-parent) - Application framework
• Java 21 - Required Java version
• Spring AI MCP Server 1.1.0-M2 (spring-ai-starter-mcp-server-webmvc) - MCP protocol implementation with SSE transport
• MCP Annotations 0.4.1 (mcp-annotations) - Declarative tool definitions via @McpTool and @McpToolParam
• Spring WebFlux (spring-webflux) - Reactive WebClient for SearXNG HTTP communication
• Spring Boot Actuator (spring-boot-starter-actuator) - Health check endpoints

Data Models

The service uses Java records for clean, immutable data structures:

• SearxngResponse(String query, List<SearxngResult> results, List<String> suggestions)
• SearxngResult(String url, String title, String content, String engine, Double score)

Docker Build

Multi-stage Dockerfile for optimized image size:

1. Builder: Maven build on maven:3.9.8-eclipse-temurin-21
2. Runtime: Minimal openjdk:21-jdk-slim with compiled JAR

🔍 Troubleshooting

📄 License

This project is open source. Feel free to contribute!

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request