nitish-raj/searxng-mcp-bridge

SearXNG MCP Bridge Server

This is a Model Context Protocol (MCP) server that acts as a bridge to a SearXNG instance. It allows compatible clients to perform searches using a configured SearXNG instance via MCP tools.

Quick Start (Using from npm)

1. Set up a SearXNG instance:

   # Using Docker
   docker run -d -p 8888:8080 --name searxng searxng/searxng
   

2. Install and run the MCP bridge:

   # Run directly with npx
   npx @nitish-raj/searxng-mcp-bridge
   

3. Configure in your MCP settings file: Add to your MCP settings file (e.g., ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json):

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "npx",
         "args": ["@nitish-raj/searxng-mcp-bridge"],
         "env": {
           "SEARXNG_INSTANCE_URL": "YOUR_SEARXNG_INSTANCE_URL" # Replace with your instance URL (e.g., http://localhost:8888 or a public one)
         },
         "disabled": false
       }
     }
   }
   

Features

• Provides an MCP tool named search.
• Connects to a SearXNG instance specified by an environment variable.
• Returns search results from SearXNG in JSON format.

Prerequisites

• Node.js and npm installed.
• A running SearXNG instance accessible from where this server will run.

Installation & Configuration

Installing via Smithery

To install searxng-mcp-bridge for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @nitish-raj/searxng-mcp-bridge --client claude

Option 1: Using npm (Recommended)

1. Install the package globally:

   npm install -g @nitish-raj/searxng-mcp-bridge
   

2. Add to MCP Settings: Add the following configuration to your MCP settings file (e.g., ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json):

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "mcp-searxng-bridge",
         "env": {
           "SEARXNG_INSTANCE_URL": "YOUR_SEARXNG_INSTANCE_URL" # Replace with your instance URL (e.g., http://localhost:8888 or a public one)
         },
         "disabled": false,
         "alwaysAllow": ["search"] // Optional: Allow search without confirmation
       }
     }
   }
   

   • Crucially, set the SEARXNG_INSTANCE_URL environment variable in the env section to the URL of the SearXNG instance the bridge should connect to (e.g., http://localhost:8888 or a public instance like https://searx.space/). This variable is mandatory.

Option 2: From Source

1. Clone the repository:

   git clone https://github.com/nitish-raj/searxng-mcp-bridge.git
   cd searxng-mcp-bridge
   npm install
   npm run build
   

2. Add to MCP Settings: Add the following configuration to your MCP settings file:

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "node",
         "args": [
           "/path/to/searxng-mcp-bridge/build/index.js" // Adjust path if needed
         ],
         "env": {
           "SEARXNG_INSTANCE_URL": "YOUR_SEARXNG_INSTANCE_URL" # Replace with your instance URL (e.g., http://localhost:8888 or a public one)
         },
         "disabled": false
       }
     }
   }
   

   • Replace /path/to/searxng-mcp-bridge/build/index.js with the actual path to the built server file.

3. Restart MCP Client: Restart the application using MCP (e.g., VS Code with the Roo extension) to load the new server configuration.

Setting up SearXNG

You need a running SearXNG instance to use this bridge. Here are some options:

1. Using Docker (Recommended):

   docker run -d -p 8888:8080 --name searxng searxng/searxng
   

2. Using Docker Compose: Create a docker-compose.yml file:

   version: '3'
   services:
     searxng:
       image: searxng/searxng
       ports:
         - "8888:8080"
       restart: unless-stopped
   

   Then run:

   docker-compose up -d
   

3. For more advanced configuration options, refer to the SearXNG documentation.

Usage

Once configured, you can instruct your MCP client (like Roo) to use the tool:

"Use the searxng-bridge search tool to search for 'your query'"

Development

• npm install: Install dependencies.
• npm run build: Compile TypeScript to JavaScript.
• npm run watch: Watch for changes and rebuild automatically.
• npm run inspector: Run the MCP inspector to test the server.

Release Process

This project uses GitHub Actions for continuous integration and deployment:

Initial Setup (First-time only)

1. Push the code to GitHub:

   # Initialize git if not already done
   git init
   git add .
   git commit -m "Initial commit"
   
   # Add your GitHub repository as remote
   git remote add origin https://github.com/nitish-raj/searxng-mcp-bridge.git
   git push -u origin main
   

2. Set up npm access:

   # Login to npm (you'll need an npm account)
   npm login
   
   # Generate an access token for GitHub Actions
   # Go to npmjs.com → User Settings → Access Tokens → Generate New Token
   

3. Add the npm token to GitHub repository secrets:

   • Go to your GitHub repository
   • Navigate to Settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: NPM_TOKEN
   • Value: [Your npm access token]
   • Click "Add secret"

4. Validate your package before publishing (optional):

   • After pushing your code to GitHub, go to the "Actions" tab
   • Select the "Validate Package" workflow
   • Click "Run workflow"
   • This will build and pack your package without publishing it
   • You can download the packed package as an artifact to inspect it

Release Process

1. Continuous Integration: Every push to main and pull request is automatically built and tested.

2. Release Management: When a new version is ready to be released:

   # For a patch release (0.1.0 -> 0.1.1)
   npm run release:patch
   
   # For a minor release (0.1.0 -> 0.2.0)
   npm run release:minor
   
   # For a major release (0.1.0 -> 1.0.0)
   npm run release:major
   

   This will:

   • Update the version in package.json.
   • Automatically update CHANGELOG.md based on commit messages since the last tag (using conventional-changelog-cli). Ensure conventional-changelog-cli is installed (npm install --save-dev conventional-changelog-cli) and use Conventional Commits (e.g., feat: ..., fix: ...) for meaningful changelog entries.
   • Create a git commit and tag locally.

3. Publishing:

   # Push the commit and tag
   git push && git push --tags
   

   The GitHub Actions workflow will automatically:

   • Build the project
   • Publish to npm
   • Create a GitHub release

The CHANGELOG.md file is automatically updated by the release script based on conventional commit messages.

Contributing

Contributions are welcome!

Please see the GitHub repository for contribution guidelines.