SearXNG MCP Server for LM Studio

A Model Context Protocol (MCP) server that provides web search capabilities to local LLMs running in LM Studio using a privacy-focused local SearXNG instance.

Features

• Web Search: Search the web using your local SearXNG instance
• Concurrent Searches: Execute multiple searches simultaneously
• Result Caching: Automatic caching with configurable TTL to reduce API calls
• Advanced Filtering: Filter results by domain, deduplicate, and limit results
• Privacy-First: All searches run through your local SearXNG instance
• High Performance: Built with TypeScript and async/await for optimal performance

Quick Start

1. Install and Build

# Clone the repository
git clone https://github.com/Pascalrjt/SearXNG-Websearch-MCP.git
cd SearXNG-Websearch-MCP

# Install dependencies and build
npm install
npm run build

2. Start SearXNG

npm run docker:up

Verify SearXNG is running by visiting http://localhost:8080 in your browser.

3. Configure LM Studio

Add to your LM Studio MCP configuration file:

{
  "mcpServers": {
    "websearch-searxng": {
      "command": "node",
      "args": ["/path/to/SearXNG-Websearch-MCP/dist/index.js"],
      "env": {}
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/LM Studio/mcp_config.json
• Windows: %APPDATA%\LM Studio\mcp_config.json
• Linux: ~/.config/lm-studio/mcp_config.json

Note: Replace /path/to/SearXNG-Websearch-MCP with your actual installation path.

4. Restart LM Studio

Close and reopen LM Studio for the MCP server to be recognized.

5. Test It Out

Try asking your LLM:

Search for "quantum computing breakthroughs 2024" and summarize the top findings

Prerequisites

• Node.js 18 or higher
• Docker and Docker Compose
• LM Studio

System Prompt

The repository includes prompt.md, a comprehensive system prompt that guides your LLM to effectively use the web search tools. This prompt teaches the LLM to:

• Always determine current date for time-sensitive queries
• Verify facts across multiple sources
• Use advanced filtering (domains, time ranges, categories)
• Handle concurrent searches for complex research
• Properly manage the search cache

Using the System Prompt in LM Studio

1. Open prompt.md in the repository
2. Copy the entire contents
3. In LM Studio, go to Settings → System Prompt
4. Paste the prompt

The LLM will now automatically use web search tools more effectively, providing better research and verification of facts.

Detailed Installation

1. Clone the Repository

git clone <repository-url>
cd websearch-searXNG

2. Install Dependencies

npm install

3. Start SearXNG Docker Container

npm run docker:up

This will start SearXNG on http://localhost:8080. You can verify it's running by visiting this URL in your browser.

4. Build the MCP Server

npm run build

Available Tools

1. web_search

Perform a single web search with advanced filtering options.

Parameters:

• query (required): The search query string
• maxResults (optional, default: 10): Maximum number of results to return
• language (optional): Language code for results (e.g., "en", "es", "fr")
• timeRange (optional): Filter by time ("day", "week", "month", "year")
• categories (optional): Array of categories (e.g., ["general", "news"])
• includeDomains (optional): Only include results from these domains
• excludeDomains (optional): Exclude results from these domains
• deduplicateByDomain (optional, default: false): Return only one result per domain

2. multi_search

Perform multiple searches concurrently for efficient information gathering.

Parameters:

• queries (required): Array of search query objects
  • Each query can have: query, maxResults, language, timeRange, categories
• globalFilters (optional): Filters to apply to all results
  • includeDomains, excludeDomains, deduplicateByDomain

3. clear_cache

Clear the search results cache to free memory or force fresh results.

Parameters: None

Usage Examples

Basic Search

Search for "climate change solutions" and summarize the findings

Time-Filtered Search

Search for news about "artificial intelligence" from the last week

Domain-Specific Search

Search for "TypeScript best practices" but only show results from
official documentation sites like typescriptlang.org and microsoft.com

Exclude Domains

Search for recent news about "renewable energy" from the last month,
excluding results from social media domains

Multiple Concurrent Searches

I need to compare three topics. Search for:
1. "rust programming language advantages"
2. "golang performance benchmarks"
3. "python async programming"

Summarize the key differences between these languages.

Complex Research Query

I need information on "quantum computing", "artificial intelligence ethics",
and "blockchain technology". Search for all three and compare their current state.

Docker Management

Start SearXNG

npm run docker:up

Stop SearXNG

npm run docker:down

View SearXNG Logs

npm run docker:logs

Access SearXNG Web Interface

Open your browser and navigate to: http://localhost:8080

Development

Build TypeScript

npm run build

Watch Mode (for development)

npm run dev

Architecture

┌─────────────┐
│  LM Studio  │
└──────┬──────┘
       │ MCP Protocol
       │
┌──────▼──────────────┐
│  MCP Server         │
│  (index.ts)         │
└──────┬──────────────┘
       │
┌──────▼──────────────┐
│  SearXNG Client     │
│  (searxng-client.ts)│
│                     │
│  ┌───────────────┐  │
│  │ Cache System  │  │
│  └───────────────┘  │
└──────┬──────────────┘
       │ HTTP API
       │
┌──────▼──────────────┐
│  SearXNG Instance   │
│  (Docker Container) │
│  localhost:8080     │
└─────────────────────┘

Caching Behavior

• Search results are cached for 5 minutes by default
• Cache key is generated from search parameters
• Automatic cleanup of expired entries every minute
• Use clear_cache tool to manually clear the cache

Filtering Capabilities

Domain Filtering

• Include Domains: Only show results from specified domains
• Exclude Domains: Filter out results from specified domains

Result Limiting

• Max Results: Limit the number of results returned
• Deduplicate by Domain: Show only one result per domain

Time Range Filtering

• Day: Results from the last 24 hours
• Week: Results from the last 7 days
• Month: Results from the last 30 days
• Year: Results from the last 365 days

Troubleshooting

MCP Server Not Connecting in LM Studio

1. Verify the build completed successfully: npm run build
2. Check the dist folder exists: ls dist/index.js
3. Ensure the path in LM Studio config is absolute and correct
4. Restart LM Studio completely

Search Returns No Results

1. Verify SearXNG is running: Visit http://localhost:8080 in browser
2. Test the API: curl "http://localhost:8080/search?q=test&format=json"
3. Clear cache using the clear_cache tool
4. Check Docker logs: npm run docker:logs

SearXNG Container Not Starting

# Check if port 8080 is already in use
lsof -i :8080

# View container logs
npm run docker:logs

# Restart the container
npm run docker:down && npm run docker:up

Cache Issues

Use the clear_cache tool in LM Studio, or restart LM Studio to restart the MCP server.

Performance Tips

1. Use Caching: Results are cached automatically for 5 minutes
2. Concurrent Searches: Use multi_search for multiple queries instead of sequential searches
3. Filter Early: Use maxResults to limit results and reduce processing
4. Domain Filtering: Filter by domain to get more relevant results faster
5. System Prompt: Use the included prompt.md to teach your LLM optimal search strategies

Security & Privacy

• All searches run through your local SearXNG instance
• No data sent to external MCP providers
• SearXNG can be configured to use specific search engines
• Full control over search privacy settings

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

If you encounter issues:

1. Check the Troubleshooting section above
2. Review SearXNG logs: npm run docker:logs
3. Verify your Node.js version: node --version (should be 18+)
4. Ensure Docker is running properly
5. Check that paths in LM Studio config are correct and absolute