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"

Release Process

This project uses GitHub Actions for automated and manual releases.

Automated Releases (for Renovate)

When a pull request from Renovate is merged, the release.yml workflow is automatically triggered. This workflow handles the following:

• Bumps the minor version of the package.
• Updates the CHANGELOG.md with the latest changes.
• Publishes the new version to the npm registry.
• Creates a GitHub release with the corresponding tag and changelog.

This process is fully automated and requires no manual intervention for dependency updates.

Manual Releases

To create a manual release, follow these steps:

1. Update the version locally: Use the npm version command to bump the package version and create a corresponding git tag. This will also update the CHANGELOG.md file.

   # For a patch release (e.g., 0.1.0 -> 0.1.1)
   npm version patch
   
   # For a minor release (e.g., 0.1.0 -> 0.2.0)
   npm version minor
   
   # For a major release (e.g., 0.1.0 -> 1.0.0)
   npm version major
   

2. Push the changes to GitHub: Push the commit and the newly created tag to the main branch.

   git push && git push --tags
   

3. Trigger the release workflow: Pushing the tag will trigger the release.yml workflow, which will build the package, publish it to npm, and create a GitHub release.

Contributing

Contributions are welcome!

Please see the GitHub repository for contribution guidelines.