mcp-omnisearch

A Model Context Protocol (MCP) server that provides unified access to multiple search providers and AI tools. This server combines the capabilities of Tavily, Brave, Kagi, Exa AI, GitHub, Linkup, and Firecrawl to offer comprehensive search, AI responses, and content processing through four consolidated tools.

Features

🔍 `web_search` — Web Search

Search the web for information. Providers: tavily (factual/citations), brave (privacy/operators), kagi (quality/operators), exa (AI-semantic), kagi_enrichment (specialized indexes).

Parameters:

query (string, required): Search query
provider (string, required): tavily, brave, kagi, exa, or kagi_enrichment
limit (number, optional): Maximum number of results (default: 10)
include_domains (array, optional): Only return results from these domains
exclude_domains (array, optional): Exclude results from these domains

🤖 `ai_search` — AI-Powered Answers

Get AI-powered answers with citations and reasoning. Providers: kagi_fastgpt (fast ~900ms answers), exa_answer (semantic AI), linkup (deep agentic search with sources).

Parameters:

query (string, required): Question or search query
provider (string, required): kagi_fastgpt, exa_answer, or linkup
limit (number, optional): Maximum number of results (default: 10)

🔎 `github_search` — GitHub Search

Search GitHub for code, repositories, or users. Supports advanced syntax: filename:, path:, repo:, user:, language:, in:file.

Parameters:

query (string, required): Search query
search_type (string, optional): code, repositories, or users (default: code)
limit (number, optional): Maximum number of results (default: 10)
sort (string, optional): stars, forks, or updated (repositories only)

📄 `web_extract` — Content Extraction and Processing

Extract, process, or summarize web content from URLs. Providers: tavily (content extraction), kagi (summarization of pages/videos/podcasts), firecrawl (scraping/crawling/mapping/structured extraction/interactive), exa (content retrieval/similar pages).

Parameters:

url (string or array, required): URL or array of URLs to process
provider (string, required): tavily, kagi, firecrawl, or exa
mode (string, optional): Processing mode. Firecrawl: scrape/crawl/map/extract/actions. Exa: contents/similar. Tavily: extract. Kagi: summarize. Defaults to provider default.
extract_depth (string, optional): basic or advanced (default: basic)

🎯 Search Operators

MCP Omnisearch provides powerful search capabilities through operators and parameters:

Search Operator Reference

Brave & Kagi Operators (use in query string):

Domain: site:example.com, -site:example.com
File type: filetype:pdf or ext:pdf
Location: intitle:term, inurl:term, inbody:term, inpage:term
Language: lang:en (ISO 639-1 codes)
Country: loc:us (ISO 3166-1 codes)
Date: before:2024, after:2024-01-01
Exact: "exact phrase"
Include/Exclude: +required, -excluded

Tavily (API parameters only):

Domain filtering: include_domains, exclude_domains

Example Usage

// Brave/Kagi: Advanced operators in query
{
  "query": "filetype:pdf lang:en site:microsoft.com +typescript -javascript",
  "provider": "brave"
}

// Brave/Kagi: Search gists
{
  "query": "site:gist.github.com claude code settings",
  "provider": "brave"
}

// Tavily: API parameters for domain filtering
{
  "query": "typescript guide",
  "provider": "tavily",
  "include_domains": ["microsoft.com"]
}

Provider Capabilities

Brave Search: Full native operator support in query string
Kagi Search: Complete operator support in query string
Tavily Search: Domain filtering through API parameters
Exa Search: Domain filtering through API parameters, semantic search with neural understanding
GitHub Search: Advanced code search syntax with qualifiers:
- filename:remote.ts - Search for specific files
- path:src/lib - Search within specific directories
- repo:user/repo - Search within specific repositories
- user:username - Search within a user's repositories
- language:typescript - Filter by programming language
- in:file "export function" - Search for text within files

Flexible API Key Requirements

MCP Omnisearch is designed to work with the API keys you have available. You don't need to have keys for all providers - the server will automatically detect which API keys are available and only enable those providers.

For example:

If you only have a Tavily and Brave API key, only those providers will be available
If you don't have a Kagi API key, Kagi-based services won't be available, but all other providers will work normally
The server will log which providers are available based on the API keys you've configured

This flexibility makes it easy to get started with just one or two providers and add more as needed.

Configuration

This server requires configuration through your MCP client. Here are examples for different environments:

Cline Configuration

Add this to your Cline MCP settings:

{
	"mcpServers": {
		"mcp-omnisearch": {
			"command": "node",
			"args": ["/path/to/mcp-omnisearch/dist/index.js"],
			"env": {
				"TAVILY_API_KEY": "your-tavily-key",
				"KAGI_API_KEY": "your-kagi-key",
				"BRAVE_API_KEY": "your-brave-key",
				"GITHUB_API_KEY": "your-github-key",
				"EXA_API_KEY": "your-exa-key",
				"LINKUP_API_KEY": "your-linkup-key",
				"FIRECRAWL_API_KEY": "your-firecrawl-key",
				"FIRECRAWL_BASE_URL": "http://localhost:3002"
			},
			"disabled": false,
			"autoApprove": []
		}
	}
}

Claude Desktop with WSL Configuration

For WSL environments, add this to your Claude Desktop configuration:

{
	"mcpServers": {
		"mcp-omnisearch": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"TAVILY_API_KEY=key1 KAGI_API_KEY=key2 BRAVE_API_KEY=key3 GITHUB_API_KEY=key4 EXA_API_KEY=key5 LINKUP_API_KEY=key6 FIRECRAWL_API_KEY=key7 FIRECRAWL_BASE_URL=http://localhost:3002 node /path/to/mcp-omnisearch/dist/index.js"
			]
		}
	}
}

Environment Variables

The server uses API keys for each provider. You don't need keys for all providers - only the providers corresponding to your available API keys will be activated:

TAVILY_API_KEY: For Tavily Search and content extraction
KAGI_API_KEY: For Kagi services (Search, FastGPT, Summarizer, Enrichment)
BRAVE_API_KEY: For Brave Search
GITHUB_API_KEY: For GitHub search services (Code, Repository, User search)
EXA_API_KEY: For Exa AI services (Search, Answer, Contents, Similar)
LINKUP_API_KEY: For Linkup AI search with sourced answers
FIRECRAWL_API_KEY: For Firecrawl services (Scrape, Crawl, Map, Extract, Actions)
FIRECRAWL_BASE_URL: For self-hosted Firecrawl instances (optional, defaults to Firecrawl cloud service)

You can start with just one or two API keys and add more later as needed. The server will log which providers are available on startup.

GitHub API Key Setup

To use GitHub search features, you'll need a GitHub personal access token with public repository access only for security:

Go to GitHub Settings: Navigate to GitHub Settings > Developer settings > Personal access tokens
Create a new token: Click "Generate new token" → "Generate new token (classic)"
Configure token settings:
- Name: MCP Omnisearch - Public Search
- Expiration: Choose your preferred expiration (90 days recommended)
- Scopes: Leave all checkboxes UNCHECKED
  
  ⚠️ Important: Do not select any scopes. An empty scope token can only access public repositories and user profiles, which is exactly what we want for search functionality.
Generate and copy: Click "Generate token" and copy the token immediately
Add to environment: Set GITHUB_API_KEY=your_token_here

Security Notes:

This token configuration ensures no access to private repositories
Only public code search, repository discovery, and user profiles are accessible
Rate limits: 5,000 requests/hour for code search, 10 requests/minute for code search specifically
You can revoke the token anytime from GitHub settings if needed

Self-Hosted Firecrawl Configuration

If you're running a self-hosted instance of Firecrawl, you can configure MCP Omnisearch to use it by setting the FIRECRAWL_BASE_URL environment variable. This allows you to maintain complete control over your data processing pipeline.

Self-hosted Firecrawl setup:

Follow the Firecrawl self-hosting guide
Set up your Firecrawl instance (default runs on http://localhost:3002)
Configure MCP Omnisearch with your self-hosted URL:

FIRECRAWL_BASE_URL=http://localhost:3002
# or for a remote self-hosted instance:
FIRECRAWL_BASE_URL=https://your-firecrawl-domain.com

Important notes:

If FIRECRAWL_BASE_URL is not set, MCP Omnisearch will default to the Firecrawl cloud service
Self-hosted instances support the same API endpoints (/v1/scrape, /v1/crawl, etc.)
You'll still need a FIRECRAWL_API_KEY even for self-hosted instances
Self-hosted Firecrawl provides enhanced security and customization options

API

The server exposes 4 consolidated MCP tools. Each tool dispatches to the provider you select:

web_search

Search the web for information.

{
	"query": "latest developments in quantum computing",
	"provider": "tavily"
}

{
	"query": "rust programming language features site:github.com",
	"provider": "brave",
	"limit": 15
}

{
	"query": "latest AI research papers",
	"provider": "exa",
	"include_domains": ["arxiv.org", "scholar.google.com"]
}

ai_search

Get AI-powered answers with citations.

{
	"query": "Explain the differences between REST and GraphQL",
	"provider": "kagi_fastgpt"
}

{
	"query": "How does machine learning work?",
	"provider": "exa_answer"
}

{
	"query": "What are the latest advances in quantum computing?",
	"provider": "linkup"
}

github_search

Search GitHub for code, repositories, or users.

{
	"query": "filename:remote.ts @sveltejs/kit",
	"search_type": "code",
	"limit": 5
}

{
	"query": "sveltekit remote functions",
	"search_type": "repositories",
	"sort": "stars"
}

{
	"query": "Rich-Harris",
	"search_type": "users",
	"limit": 3
}

web_extract

Extract, process, or summarize web content from URLs.

{
	"url": "https://example.com/long-article",
	"provider": "kagi",
	"mode": "summarize"
}

{
	"url": [
		"https://example.com/article1",
		"https://example.com/article2"
	],
	"provider": "tavily"
}

{
	"url": "https://example.com",
	"provider": "firecrawl",
	"mode": "crawl",
	"extract_depth": "advanced"
}

{
	"url": "https://arxiv.org/abs/2106.09685",
	"provider": "exa",
	"mode": "similar"
}

Docker Deployment

MCP Omnisearch supports containerized deployment using Docker with MCPO (Model Context Protocol Over HTTP) integration, enabling cloud deployment and OpenAPI access.

Quick Start with Docker

Using Docker Compose (Recommended):

# Clone the repository
git clone https://github.com/spences10/mcp-omnisearch.git
cd mcp-omnisearch

# Create .env file with your API keys
echo "TAVILY_API_KEY=your-tavily-key" > .env
echo "KAGI_API_KEY=your-kagi-key" >> .env
echo "BRAVE_API_KEY=your-brave-key" >> .env
echo "EXA_API_KEY=your-exa-key" >> .env
echo "GITHUB_API_KEY=your-github-key" >> .env
# Add other API keys as needed
echo "LINKUP_API_KEY=your-linkup-key" >> .env

# Start the container
docker-compose up -d

Using Docker directly:

docker build -t mcp-omnisearch .
docker run -d \
  -p 8000:8000 \
  -e TAVILY_API_KEY=your-tavily-key \
  -e KAGI_API_KEY=your-kagi-key \
  -e BRAVE_API_KEY=your-brave-key \
  -e EXA_API_KEY=your-exa-key \
  -e GITHUB_API_KEY=your-github-key \
  -e LINKUP_API_KEY=your-linkup-key \
  --name mcp-omnisearch \
  mcp-omnisearch

Container Environment Variables

Configure the container using environment variables for each provider:

TAVILY_API_KEY: For Tavily Search and content extraction
KAGI_API_KEY: For Kagi services (Search, FastGPT, Summarizer, Enrichment)
BRAVE_API_KEY: For Brave Search
GITHUB_API_KEY: For GitHub search services
EXA_API_KEY: For Exa AI services
LINKUP_API_KEY: For Linkup AI search
FIRECRAWL_API_KEY: For Firecrawl services
FIRECRAWL_BASE_URL: For self-hosted Firecrawl instances (optional)
PORT: Container port (defaults to 8000)

OpenAPI Access

Once deployed, the MCP server is accessible via OpenAPI at:

Base URL: http://your-container-host:8000
OpenAPI Endpoint: /omnisearch
Compatible with: OpenWebUI and other tools expecting OpenAPI

Cloud Deployment

The containerized version can be deployed to any container platform that supports Docker:

Cloud Run (Google Cloud)
Container Instances (Azure)
ECS/Fargate (AWS)
Railway, Render, Fly.io
Any Kubernetes cluster

Example deployment to a cloud platform:

# Build and tag for your registry
docker build -t your-registry/mcp-omnisearch:latest .
docker push your-registry/mcp-omnisearch:latest

# Deploy with your platform's CLI or web interface
# Configure environment variables through your platform's settings

Development

Setup

Clone the repository
Install dependencies:

pnpm install

Build the project:

pnpm run build

Run in development mode:

pnpm run dev

Publishing

Update version in package.json
Build the project:

pnpm run build

Publish to npm:

pnpm publish

Troubleshooting

API Keys and Access

Each provider requires its own API key and may have different access requirements:

Tavily: Requires an API key from their developer portal
Kagi: Some features limited to Business (Team) plan users
Brave: API key from their developer portal
GitHub: Personal access token with no scopes selected (public access only)
Exa AI: API key from their dashboard at dashboard.exa.ai
Linkup: API key from their developer portal
Firecrawl: API key required from their developer portal

Rate Limits

Each provider has its own rate limits. The server will handle rate limit errors gracefully and return appropriate error messages.

Contributing

Please read CONTRIBUTING.md before opening a PR. In short:

Start by opening an issue to propose your change and align scope.
Prefer small, focused PRs with a clear explanation (problem → approach → verification).
Follow provider conventions: use src/common/http.ts (http_json) for HTTP, read keys from src/config/env.ts, respect timeouts, and surface errors via ProviderError.

License

MIT License - see the LICENSE file for details.

Acknowledgments

Built on:

Name		Name	Last commit message	Last commit date
Latest commit History 213 Commits
.changeset		.changeset
.github		.github
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
renovate.json		renovate.json
server.json		server.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

mcp-omnisearch

Features

🔍 web_search — Web Search

🤖 ai_search — AI-Powered Answers

🔎 github_search — GitHub Search

📄 web_extract — Content Extraction and Processing

🎯 Search Operators

Search Operator Reference

Example Usage

Provider Capabilities

Flexible API Key Requirements

Configuration

Cline Configuration

Claude Desktop with WSL Configuration

Environment Variables

GitHub API Key Setup

Self-Hosted Firecrawl Configuration

API

web_search

ai_search

github_search

web_extract

Docker Deployment

Quick Start with Docker

Container Environment Variables

OpenAPI Access

Cloud Deployment

Development

Setup

Publishing

Troubleshooting

API Keys and Access

Rate Limits

Contributing

License

Acknowledgments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

🔍 `web_search` — Web Search

🤖 `ai_search` — AI-Powered Answers

🔎 `github_search` — GitHub Search

📄 `web_extract` — Content Extraction and Processing

Packages