What is Searxng Mcp Bridge

searxng-mcp-bridge is a Model Context Protocol (MCP) server that serves as a bridge to a SearxNG instance, enabling compatible clients to perform searches through MCP tools.

Use cases

Use cases include integrating search capabilities into applications, enhancing data retrieval processes, and enabling custom search solutions for developers and organizations.

How to use

To use searxng-mcp-bridge, first set up a SearxNG instance using Docker. Then, install and run the MCP bridge using npx. Finally, configure your MCP settings file to include the bridge with the appropriate SearxNG instance URL.

Key features

Key features include providing an MCP tool named ‘search’, connecting to a specified SearxNG instance via an environment variable, and returning search results in JSON format.

Where to use

searxng-mcp-bridge can be used in various fields such as software development, data analysis, and anywhere that requires integration with search functionalities provided by SearxNG.

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):

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):

   • 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:

   • 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.