# Parallel Search MCP

An MCP server that brings [Parallel](https://parallel.ai/) 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](https://platform.parallel.ai/)
- An MCP-compatible client

## Installation

Install globally from npm:

```bash
npm install --global parallel-search-mcp
```

Or clone the repository:

```bash
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:

```bash
export PARALLEL_API_KEY="your-api-key"
```

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

```bash
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:

```toml
[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:

```toml
[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:

```bash
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:

```json
{
  "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:

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

## Development

Start the stdio MCP server:

```bash
npm start
```

Run the test suite:

```bash
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:

```bash
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.