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:

1. Go to GitHub Settings: Navigate to
   GitHub Settings > Developer settings > Personal access tokens

2. Create a new token: Click "Generate new token" → "Generate new
   token (classic)"

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

4. Generate and copy: Click "Generate token" and copy the token
   immediately

5. 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:

1. Follow the
   Firecrawl self-hosting guide
2. Set up your Firecrawl instance (default runs on
   http://localhost:3002)
3. 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

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

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

1. Clone the repository
2. Install dependencies:

pnpm install

1. Build the project:

pnpm run build

1. Run in development mode:

pnpm run dev

Publishing

1. Update version in package.json
2. Build the project:

pnpm run build

1. 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:

• Model Context Protocol
• Tavily Search
• Kagi Search
• Brave Search
• Exa AI
• Linkup
• Firecrawl