Parallel Search MCP

An MCP server that brings Parallel web search and URL extraction to Codex and other Model Context Protocol clients.

It exposes two read-only tools:

• parallel_search searches the web with selectable turbo, basic, and advanced modes.
• parallel_fetch extracts focused excerpts or full Markdown content from up to 20 known URLs.

Both tools return MCP structured content alongside a readable text response, default to a 25,000-character output limit, and retry transient network or HTTP failures up to three attempts.

Requirements

• Node.js 18 or newer
• A Parallel API key from platform.parallel.ai
• An MCP-compatible client

Installation

Install globally from npm:

npm install --global parallel-search-mcp

Or clone the repository:

git clone https://github.com/L-Chris/parallel-search-mcp.git
cd parallel-search-mcp
npm ci

API key

Set the key in the environment that launches your MCP client:

export PARALLEL_API_KEY="your-api-key"

Alternatively, save the key at ~/.config/parallel/api_key and restrict access to the file:

mkdir -p ~/.config/parallel
chmod 700 ~/.config/parallel
printf '%s' 'your-api-key' > ~/.config/parallel/api_key
chmod 600 ~/.config/parallel/api_key

PARALLEL_API_KEY takes precedence over the key file. Set PARALLEL_API_KEY_FILE to use a different key-file path.

Never commit an API key to this repository or place one directly in an MCP configuration file.

Codex configuration

Add the following to ~/.codex/config.toml, replacing the path with the absolute path to your clone:

[mcp_servers.parallel-search-mcp]
command = "node"
args = ["/absolute/path/to/parallel-search-mcp/server.mjs"]
env_vars = ["PARALLEL_API_KEY"]

For a global npm installation, the executable can be configured directly:

[mcp_servers.parallel-search-mcp]
command = "parallel-search-mcp"
env_vars = ["PARALLEL_API_KEY"]

Restart Codex after changing the configuration. You can verify registration with:

codex mcp list

Tools

parallel_search

Searches the web through the Parallel Search API.

Important inputs:

• search_queries: one to five concise search queries; required.
• objective: a self-contained description of what the search should answer.
• mode: turbo, basic, or advanced.
• max_results: maximum number of results, from 1 to 20.
• include_domains / exclude_domains: domain filters.
• after_date: earliest publication date in YYYY-MM-DD form.
• max_chars_total: total output character limit.

When mode is omitted, Chinese queries use basic; other queries, including Japanese text containing kana, use turbo. Choose advanced explicitly when result quality matters more than latency.

Example input:

{
  "objective": "Find recent official Model Context Protocol announcements",
  "search_queries": ["official MCP announcements"],
  "mode": "advanced",
  "include_domains": ["modelcontextprotocol.io"],
  "max_results": 5
}

parallel_fetch

Extracts relevant content from known URLs through the Parallel Extract API.

Important inputs:

• urls: one to twenty URLs; required.
• objective and search_queries: focus the extracted excerpts.
• max_chars_per_result: per-page excerpt limit.
• full_content: include full Markdown content.
• full_content_max_chars_per_result: enable and cap full content per page.
• max_age_seconds, timeout_seconds, and disable_cache_fallback: fetching controls.

Example input:

{
  "urls": ["https://modelcontextprotocol.io/"],
  "objective": "Extract the project overview and key concepts",
  "max_chars_total": 10000
}

Development

Start the stdio MCP server:

npm start

Run the test suite:

npm test

Tests use mocked HTTP responses and do not require a Parallel API key.

Publishing

Copy .env.example to .env, set NPM_TOKEN, and run:

npm run publish:npm

The publishing script loads .env, writes the npm token to a temporary user configuration with restricted permissions, publishes publicly to the official npm registry, and removes the temporary configuration afterward. .env is excluded from both Git and the npm package.

Notes

This is an independent integration and is not an official Parallel product. Use of the upstream APIs is subject to Parallel's terms and pricing.