# n8n integration

Use **Webz.io Contextual News Search** inside [n8n](https://n8n.io/) workflows and AI agents with the official community node [`n8n-nodes-webz-news-search`](https://www.npmjs.com/package/n8n-nodes-webz-news-search).

The community node calls the hosted [News Search MCP server](news-search-api-mcp) directly. Its built-in controls cover the current filters, while **Additional Fields (JSON)** can pass newer server-side fields without waiting for a node release.

n8n also ships a built-in [**MCP Client Tool**](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp) node that loads the live tool schema from the server. This gives you two ways to search Webz news:

| Approach | Best for |
| --- | --- |
| **`n8n-nodes-webz-news-search`** community node | Standalone workflows, one output item per article, and Sheets or Slack automations with no LLM |
| Built-in **MCP Client Tool** node | AI Agent workflows where the model selects filters from the live MCP schema |

Both use the same token, MCP server, search logic, credits, and rate limits. You can combine them in one workflow.

Webz is distributed as an [n8n community node](https://docs.n8n.io/integrations/community-nodes/) on npm. Find it through npm, this page, or the community-node installer in self-hosted n8n.

## Prerequisites

- n8n 2.x
- A Webz.io API token (same token as the [News Search API](news-search-api-quickstart))
- For agent workflows: an **AI Agent** node and a tool-calling chat model

The community package declares an `n8n-workflow >= 2 < 3` peer dependency. It is currently an unverified community node, so install it on self-hosted n8n. On n8n Cloud, use the built-in MCP Client Tool.

Get your token from the [Webz.io dashboard](https://webz.io).

## Install the community node

In self-hosted n8n, open **Settings > Community nodes > Install**, enter the package name, acknowledge the risk prompt, and install:

```
n8n-nodes-webz-news-search
```

Package: [npmjs.com/package/n8n-nodes-webz-news-search](https://www.npmjs.com/package/n8n-nodes-webz-news-search)  
Source: [github.com/Webhose/webz-news-search/packages/n8n-node](https://github.com/Webhose/webz-news-search/tree/master/packages/n8n-node)

The package has zero runtime npm dependencies and uses n8n's HTTP helpers.

> [!NOTE]
> Current n8n releases create the AI tool variant automatically from the node's `usableAsTool` setting. If an older self-hosted n8n 2.x release does not expose it, set `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true` and restart n8n.

## Credentials

Add a **Webz.io News Search API** credential and paste your Webz.io API token.

The credential test calls MCP `initialize` only, so saving it does not consume search credits.

Paste the token even if it already exists in a `.env` file on the host. n8n keeps credentials in its own encrypted store and does not read your project's environment for this credential.

## Quick start: direct search

No LLM required:

1. Add a **Webz.io News Search** node to a workflow.
2. Set **Query** to a natural-language search, such as `Nvidia earnings analyst reaction`.
3. Leave **Simplify** enabled.
4. Execute the node.

| Field | Default | Description |
| --- | --- | --- |
| Query | required | Natural-language search. Put the search subject here, not in the Topic filter |
| Limit | 50 | Maximum articles to return |
| Simplify | enabled | Split the response into one item per article |
| Additional Filters | - | Optional filter collection |

With **Simplify** enabled, each article arrives as its own n8n item:

```json
{
  "title": "Michael Burry sends another Nvidia stock verdict to investors",
  "url": "https://finance.yahoo.com/...",
  "published": "2026-08-30T20:33:00.000+03:00",
  "score": 8.6,
  "excerpt": "Nvidia earnings beat and August 27 stock reaction...",
  "query": "Nvidia earnings analyst reaction",
  "resultIndex": 1
}
```

Turn **Simplify** off to get the raw MCP text response as one `{ "result": "..." }` item.

Each execution uses your News Search API credits and rate limits, same as the MCP server or REST API.

## Filtered search

Open **Additional Filters** and add any of these optional filters. Most accept multiple values.

| Filter | Notes |
| --- | --- |
| Days | Lookback window. Leave at 0 for the server default |
| Search All Dates | Search the full indexed window instead of a lookback period |
| Language | Full names, not codes: `english`, `french`, `arabic` |
| Country | ISO-2 uppercase: `US`, `GB`, `IL` |
| Sentiment | `positive`, `negative`, `neutral` |
| Category | IPTC labels such as `Politics` or `Science and Technology` |
| Domain / Exclude Domain | Restrict to or skip source domains. A domain must not appear in both |
| Topic, Person, Organization, Location | Entity and context enrichment |
| Ticker | Uppercase symbols: `NVDA`, `AAPL` |
| Source Type, Political Bias, Trust Category | Source characteristics |
| Domain Rank >= / <= | Source rank range; lower is more popular |
| Score >= / <= | Match score 0-10. Leave at 0 to use the server default |
| Trust >= | Minimum trust score, 0.0-1.0 |
| Sort By | `best_score`, `similarity`, `date_desc`, `date_asc` |
| Allow Multiple Chunks Per Article | Return more than one matching passage from an article |
| Additional Fields (JSON) | Pass server-side fields newer than the node |

See the [MCP tool reference](news-search-api-mcp#tool-reference) and [News Search API filters](news-search-api-filters) for accepted values.

## Use with an n8n AI Agent

The community node and built-in MCP Client Tool behave differently.

### Option 1: community node as an agent tool

The package sets `usableAsTool: true`, so n8n exposes a **Webz.io News Search Tool** variant. Connect it to an **AI Agent** node's **Tool** input.

This option is available on self-hosted n8n. If an older 2.x release does not show the tool variant, set `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true` and restart n8n.

### Option 2: built-in MCP Client Tool

Add an **MCP Client Tool** node, connect it to the agent's **Tool** input, and configure:

| Field | Value |
| --- | --- |
| Endpoint | `https://news-search-mcp.webz.io/mcp` |
| Server Transport | `HTTP Streamable` |
| Authentication | `Bearer Auth` |
| Tools to Include | `All` |

Create a **Bearer Auth** credential and paste your Webz.io API token as the bearer token. The agent receives a `news_search_by_webz` tool and reads its filter schema live from the server.

Leave **Tools to Include** set to `All`. Webz exposes one tool, so narrowing the selection adds no benefit.

The MCP Client Tool is an agent sub-node and cannot run independently. For search without an LLM, use the community node.

### Example prompts for agents

- "Search Webz news for analyst reaction to Nvidia earnings. Use ticker NVDA, the last 7 days, English only, and limit to 5 results."
- "Find negative coverage about Boeing from the last 7 days using Webz news search."
- "Use the Webz news tool to compare EU and US AI regulation news from the past month, with sources."

Name the `query` argument explicitly. `topic` is a separate list-valued filter; using it for the main search subject causes a validation error.

## Ready-made templates

Four workflows are available in [`n8n/templates`](https://github.com/Webhose/webz-news-search/tree/master/n8n/templates). In n8n, choose **Import from File** from the workflow menu and select one:

| Template | What it does | Integration |
| --- | --- | --- |
| [`news-to-sheet.json`](https://github.com/Webhose/webz-news-search/blob/master/n8n/templates/news-to-sheet.json) | Manual search that appends structured article rows to Google Sheets | Community node |
| [`daily-news-digest-slack.json`](https://github.com/Webhose/webz-news-search/blob/master/n8n/templates/daily-news-digest-slack.json) | Runs every morning at 08:00 and posts a sourced digest to Slack | MCP Client Tool |
| [`ticker-monitor.json`](https://github.com/Webhose/webz-news-search/blob/master/n8n/templates/ticker-monitor.json) | Checks a ticker every 6 hours and alerts Slack on material news | MCP Client Tool |
| [`news-research-agent.json`](https://github.com/Webhose/webz-news-search/blob/master/n8n/templates/news-research-agent.json) | Chat interface for interactive news research with memory | MCP Client Tool |

### Configure a template

The adjustable values are in each workflow's **Settings** node:

| Template | Settings fields |
| --- | --- |
| `news-to-sheet.json` | `query`, `limit`, `days`, `sheetId`, `sheetName` |
| `daily-news-digest-slack.json` | `searchQuery`, `lookbackDays`, `resultCount`, `slackChannel` |
| `ticker-monitor.json` | `ticker`, `lookbackDays`, `resultCount`, `slackChannel` |

### Add credentials

Templates never include credentials, so these arrive empty:

| Node | Credential |
| --- | --- |
| Webz.io News Search community node | **Webz.io News Search API** with your Webz.io token |
| Webz.io News Search MCP Client Tool | **Bearer Auth** with your Webz.io token |
| OpenAI Chat Model | Your OpenAI key, or replace the node with another tool-calling model |
| Append rows | Google Sheets OAuth2 |
| Slack | **Slack API** with a bot token |

The three agent templates use OpenAI as a default. You can replace the chat model with Anthropic, Google, Ollama, or another tool-calling provider without changing the rest of the workflow.

For Slack, the bot token needs `chat:write` to post and `channels:read` to resolve a public channel name, plus `groups:read` for a private channel. Invite the bot with `/invite @YourApp`; otherwise Slack returns `not_in_channel`.

### Scheduled templates and timezones

Schedules use the workflow timezone and fall back to the instance timezone. Set the timezone explicitly before relying on a schedule:

- **n8n Cloud:** set the workflow timezone under **Workflow Settings > Timezone**, or configure the instance timezone
- **Self-hosted:** set the workflow timezone or the `GENERIC_TIMEZONE` environment variable

Self-hosted n8n defaults to `America/New_York` when `GENERIC_TIMEZONE` is unset.

The digest and ticker templates guard their output: they post only when the agent returns content and raise a workflow error after an agent failure rather than sending an empty message.

## How it works

```
n8n workflow
    ↓
n8n-nodes-webz-news-search (npm)   or   built-in MCP Client Tool
    ↓
Hosted MCP server: https://news-search-mcp.webz.io/mcp
    ↓
Webz News Search API
```

- **Node type:** `n8n-nodes-webz-news-search.webzNewsSearch`; n8n synthesizes `...webzNewsSearchTool` for agent use
- **Tool name:** `news_search_by_webz`
- **Schema:** built-in community-node controls plus JSON passthrough, or live `tools/list` schema through MCP Client Tool
- **Auth:** `Authorization: Bearer YOUR_WEBZ_API_TOKEN`
- **Sessions:** the community node opens one MCP session per execution and closes it afterward
- **Credits:** same as News Search API and MCP

## Configuration

| Name | Default | Description |
| --- | --- | --- |
| API Token | required | Credential field; get it from the Webz.io dashboard |
| MCP URL | `https://news-search-mcp.webz.io/mcp` | Hidden community-node credential field for testing another endpoint |
| `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE` | version-dependent | Compatibility flag for older self-hosted n8n 2.x releases |
| `GENERIC_TIMEZONE` | `America/New_York` | Self-hosted instance timezone when a workflow does not override it |

## MCP vs n8n community node

| Approach | Best for |
| --- | --- |
| [MCP Server](news-search-api-mcp) | Cursor, Claude Desktop, ChatGPT connectors |
| MCP Client Tool in n8n | n8n AI Agent workflows using the live schema |
| **n8n-nodes-webz-news-search** | Structured article rows without an LLM |

All approaches use the same token, server, search logic, credits, and rate limits. Pick the integration that matches your workflow.

## Troubleshooting

**A tool failure looks like an empty result**  
An AI Agent may catch a tool error and answer as though nothing was found. If a scheduled workflow goes quiet, inspect the search node in a recent execution.

**`Unrecognized node type: n8n-nodes-webz-news-search.webzNewsSearch`**  
Install the community package on this self-hosted instance, then re-import the workflow.

**The node does not appear in the node panel**  
Check that community and unverified packages are enabled on the self-hosted instance.

**The community node cannot be attached to an AI Agent**  
Update n8n first. On older 2.x releases, set `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true`, restart n8n, and try again.

**Empty results with `category` or `sentiment` set**  
Remove those filters and retry before concluding there is no coverage.

**Validation error on `topic`**  
`topic` expects a list of topic tags. Put the search subject in **Query**.

**`401 Unauthorized` from the MCP Client Tool**  
Confirm the **Bearer Auth** credential contains your Webz.io token and **Tools to Include** is set to `All`.

**Self-hosted n8n cannot reach the server**  
Allow outbound HTTPS from the n8n container to `news-search-mcp.webz.io`.

## Related links

- [News Search MCP Server](news-search-api-mcp)
- [News Search API filters](news-search-api-filters)
- [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
- [n8n MCP Client Tool](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp)
- [npm: n8n-nodes-webz-news-search](https://www.npmjs.com/package/n8n-nodes-webz-news-search)
- [GitHub: webz-news-search](https://github.com/Webhose/webz-news-search)