mcpbeat

News Search

brave/news-search

USE FOR news search. Returns news articles with title, URL, description, age, thumbnail. Supports freshness and date range filtering, SafeSearch filter and Goggles for custom ranking.

2k tokens
context cost
the whole folder, loaded on every use
1
files
instructions only
0
copies elsewhere
how many repositories repackaged it
164
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/brave/brave-search-skills --skill news-search

The instruction itself

14 sections, as written by the author

News Search

> Requires API Key: Get one at https://api.search.brave.com

>

> Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Quick Start (cURL)

Basic Search

curl -s "https://api.search.brave.com/res/v1/news/search?q=space+exploration" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Recent News (Past 24 Hours)

curl -s "https://api.search.brave.com/res/v1/news/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=cybersecurity" \
  --data-urlencode "country=US" \
  --data-urlencode "freshness=pd" \
  --data-urlencode "count=20"

Date Range Filter

curl -s "https://api.search.brave.com/res/v1/news/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=climate summit" \
  --data-urlencode "freshness=2026-01-01to2026-01-31"

Endpoint

GET https://api.search.brave.com/res/v1/news/search
POST https://api.search.brave.com/res/v1/news/search

Authentication: X-Subscription-Token: <API_KEY> header

Note: Both GET and POST are supported. POST is useful for long queries or complex Goggles.

Parameters

| Parameter | Type | Required | Default | Description |

|--|--|--|--|--|

| q | string | Yes | - | Search query (1-400 chars, max 50 words) |

| country | string | No | US | Search country (2-letter country code or ALL) |

| search_lang | string | No | en | Language preference (2+ char language code) |

| ui_lang | string | No | en-US | UI language (e.g., "en-US") |

| count | int | No | 20 | Number of results (1-50) |

| offset | int | No | 0 | Page offset (0-9) |

| safesearch | string | No | strict | Adult content filter (off/moderate/strict) |

| freshness | string | No | - | Time filter (pd/pw/pm/py or date range) |

| spellcheck | bool | No | true | Auto-correct query |

| extra_snippets | bool | No | - | Up to 5 additional excerpts per result |

| goggles | string or array | No | - | Custom ranking filter (URL or inline; repeat param for multiple) |

| operators | bool | No | true | Apply search operators |

| include_fetch_metadata | bool | No | false | Include fetch timestamps in results |

Freshness Values

| Value | Description |

|--|--|

| pd | Past day (24 hours) - ideal for breaking news |

| pw | Past week (7 days) |

| pm | Past month (31 days) |

| py | Past year (365 days) |

| YYYY-MM-DDtoYYYY-MM-DD | Custom date range |

Response Format

{
  "type": "news",
  "query": {
    "original": "space exploration"
  },
  "results": [
    {
      "type": "news_result",
      "title": "New Developments in Space Exploration",
      "url": "https://news.example.com/space-exploration",
      "description": "Recent missions have advanced our understanding of...",
      "age": "2 hours ago",
      "page_age": "2026-01-15T14:30:00",
      "page_fetched": "2026-01-15T15:00:00Z",
      "meta_url": {
        "scheme": "https",
        "netloc": "news.example.com",
        "hostname": "news.example.com",
        "favicon": "https://imgs.search.brave.com/favicon/news.example.com",
        "path": "/space-exploration"
      },
      "thumbnail": {
        "src": "https://imgs.search.brave.com/..."
      }
    }
  ]
}

Response Fields

| Field | Type | Description |

|--|--|--|

| type | string | Always "news" |

| query.original | string | The original search query |

| query.altered | string? | Spellcheck-corrected query (if changed) |

| query.cleaned | string? | Cleaned/normalized query from spellchecker |

| query.spellcheck_off | bool? | Whether spellcheck was disabled |

| query.show_strict_warning | bool? | True if strict safesearch blocked results |

| query.search_operators | object? | Applied search operators |

| query.search_operators.applied | bool | Whether operators were applied |

| query.search_operators.cleaned_query | string? | Query after operator processing |

| query.search_operators.sites | list[str]? | Domains from site: operators |

| results[].type | string | Always "news_result" |

| results[].title | string | Article title |

| results[].url | string | Source URL of the article |

| results[].description | string? | Article description/summary |

| results[].age | string? | Human-readable age (e.g. "2 hours ago") |

| results[].page_age | string? | Publication date from source (ISO datetime) |

| results[].page_fetched | string? | When page was last fetched (ISO datetime) |

| results[].fetched_content_timestamp | int? | Fetch timestamp (only with include_fetch_metadata=true) |

| results[].meta_url.scheme | string? | URL protocol scheme |

| results[].meta_url.netloc | string? | Network location |

| results[].meta_url.hostname | string? | Lowercased domain name |

| results[].meta_url.favicon | string? | Favicon URL |

| results[].meta_url.path | string? | URL path |

| results[].thumbnail.src | string | Served thumbnail URL |

| results[].thumbnail.original | string? | Original thumbnail URL |

| results[].extra_snippets | list[str]? | Up to 5 additional excerpts per result |

Goggles (Custom Ranking) — Unique to Brave

Goggles let you re-rank news results — boost trusted outlets or suppress unwanted sources.

| Method | Example |

|--|--|

| Hosted | --data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/hacker_news.goggle" |

| Inline | --data-urlencode 'goggles=$discard\n$site=example.com' |

> Hosted goggles must be on GitHub/GitLab, include ! name:, ! description:, ! author: headers, and be registered at https://search.brave.com/goggles/create. Inline rules need no registration.

Syntax: $boost=N / $downrank=N (1–10), $discard, $site=example.com. Combine with commas: $site=example.com,boost=3. Separate rules with \n (%0A).

Allow list: $discard\n$site=docs.python.org\n$site=developer.mozilla.org — Block list: $discard,site=pinterest.com\n$discard,site=quora.com

Resources: Discover · Syntax · Quickstart

Search Operators

Use search operators to refine results:

  • site:local-paper.com - Limit to specific news site
  • "exact phrase" - Match exact phrase
  • -exclude - Exclude term

Set operators=false to disable operator parsing.

Use Cases

  • Breaking news monitoring: Use freshness=pd for the most recent articles on a topic.
  • Custom news feeds with Goggles: Boost trusted sources and discard other sources — unique to Brave.
  • Historical news research: Use freshness=YYYY-MM-DDtoYYYY-MM-DD to find articles from specific time periods.
  • Multilingual news: Combine country, search_lang, and ui_lang for cross-locale results.
  • Data pipelines: Set include_fetch_metadata=true for fetched_content_timestamp on each result.

Notes

  • SafeSearch: Defaults to strict
  • Pagination: Use offset (0-9) with count
  • Extra snippets: Up to 5 additional excerpts when extra_snippets=true

How to use it

Copy the folder

Take brave/news-search from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.