MCP NewsAPI.ai
[CI]
[npm version]
[License: MIT]
[by Nubiia]
A Model Context Protocol (MCP) server for NewsAPI.ai (the
Event Registry news intelligence API). It lets AI assistants
like Claude search news articles and events (clusters of articles about the same
happening), resolve names to entity URIs, see what is trending, and keep an eye on the
account's token budget.
Built and maintained by Nubiia — automatización e
integraciones con IA para negocios (MCP, Holded, Pipedrive y más). ¿Quieres algo así
para tu empresa? Escríbenos en nubiia.es.
⚠️ NewsAPI.ai is metered in tokens
Every search spends tokens from your plan, and a free plan has a small budget. This
server is built to be frugal:
- Result counts default to 10 (articles/events) and article bodies to 300
characters, so a call is cheap in tokens and in your assistant's context window.
- Searches are limited to the last 31 days unless you pass
allow_archive: true
(historical data costs extra tokens per year touched). allow_archive requires
date_start and the date_start → date_end (default: today) range may span at
most 1 year. A date_start/date_end older than 31 days without allow_archive
is rejected with an explanation instead of silently returning nothing.
- A search with no filter at all is rejected locally, before it can spend anything.
- A session token budget (default 200 tokens, see below) stops runaway loops
before they reach the API.
- The
suggest_* tools and get_usage are free — use them to resolve entities to
URIs before searching.
get_usage shows the remaining budget.
Costs measured against a live account (31-day window):
Plans and pricing change — see newsapi.ai/pricing and
docs/api-notes.md.
Features
Ten read-only tools:
- Articles (2):
search_articles, get_article
- Events (2):
search_events, get_event
- Autosuggest (4):
suggest_concepts, suggest_categories, suggest_sources,
suggest_locations
- Trends (1):
get_trending_concepts
- Account (1):
get_usage
Total: 10 tools, all marked readOnlyHint: true — nothing in this server writes to
NewsAPI.ai or anywhere else.
What's deliberately out of scope for v1
Topic pages and saved searches, the analytics service (text categorization, sentiment
of arbitrary text), story clustering, article mentions, aggregation result types
(conceptAggr, timeAggr, …) and multi-tenant configuration.
Installation
Prerequisites
- Node.js 22.14 or higher
- A NewsAPI.ai account and API key, from newsapi.ai → Dashboard
Install from npm
Install from source
Configuration
Environment Variables
Session token budget
The budget is per server process: each MCP client/server instance you start has its own
counter, so two clients configured with 200 can together spend 400. It resets on restart.
Every call is charged its measured token cost (see the table above) before it is
sent. When a call would exceed the remaining budget, the tool returns an error stating the
remaining and total budget and how to raise it — and no request is sent to NewsAPI.ai.
Free tools (suggest_*, get_usage) are never blocked. get_usage also reports the
session budget (maxTokens, spentTokens, remainingTokens) next to your account
balance. Calls the API rejects outright (4xx) are refunded; calls that fail after being
accepted (including HTTP 200 {"error"} bodies) stay charged, because the API bills them.
An invalid value (e.g. abc, -5) falls back to 200 with a warning on stderr; 0
disables all paid calls.
Claude Desktop Configuration
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Or if installed from source:
Claude Code Configuration
Troubleshooting
sh: mcp-newsapi: command not found when launching from inside this repo. If you
start Claude Code (or another MCP client) from the cloned repository directory,
npx @nubiia/mcp-newsapi resolves the local package.json instead of the published
package, and the mcp-newsapi binary is not on the PATH. Pin the registry version
with @latest (as in the examples above), or launch the client from another directory.
Tools
List parameters (lang, concept_uris, category_uris, source_uris, location_uris,
ignore_source_uris, data_types, types, concept_types) accept either a single string
or an array of strings: "lang": "spa" and "lang": ["spa"] are equivalent.
The recommended flow: suggest_* (free) → search_* → get_*.
suggest_concepts · read-only · free
Resolve a name ("Telefónica", "Pedro Sánchez") to a concept URI. Pass the uri as
concept_uris to a search — far more precise than a keyword.
Searching for a company, person, place or organisation? Resolve it with
suggest_concepts first and pass the returned uri as concept_uris. keyword is for
free terms and topics and is noisy with common words: for example keyword: "Telefónica"
in Spanish also matches the ordinary adjective "telefónica".
suggest_categories, suggest_sources, suggest_locations · read-only · free
Same idea for categories (news/Business), publications (bbc.co.uk) and places.
search_articles · read-only · 1 token
At least one of keyword, concept_uris, category_uris, source_uris,
location_uris is required. Defaults: 10 results, newest first, duplicates skipped,
last 31 days, 300-character bodies. Paginate with page; the response carries total
and pages.
Dates must be real YYYY-MM-DD dates, date_end must not precede date_start, and the
archive rules above apply (allow_archive needs date_start, max 1 year).
Other options: keyword_loc, keyword_search_mode, ignore_keyword,
ignore_source_uris, data_types (news/pr/blog), sort_by
(date/rel/sourceImportance/cosSim), min_sentiment/max_sentiment,
body_len, include_duplicates, allow_archive.
get_article · read-only · 1 token
One article by article_uri, with a longer body (body_len, default 3000).
search_events · read-only · 5 tokens
Events: clusters of articles about the same happening, with title, short summary, date,
location, key concepts and article count. The right granularity for "what is happening
with X". sort_by: "size" surfaces the biggest stories; min_articles_in_event filters
noise.
get_event · read-only · 5 tokens (1 with include_articles)
One event by event_uri, or — with include_articles: true — the articles covering it.
get_trending_concepts · read-only · 10 tokens
People, organisations and places trending right now (last 2 days vs last 2 weeks) in
news, social, pr or blog (blog trends may be unavailable on some plans, and the failed call is still billed). The priciest tool: call it sparingly.
get_usage · read-only · free
availableTokens, usedTokens, remainingTokens. Check it before a batch of searches.
Rate limiting
A local guard stops runaway agent loops before they drain the token budget:
The API itself allows at most 5 simultaneous requests. 429/502/503/504 responses
and connection-refused/DNS errors are retried with backoff; ambiguous failures (timeouts,
connection resets) are not, because a metered request may already have been billed.
Each attempt times out after 30 seconds.
Error messages
A 401/403 response includes an explanation, not just "Unauthorized": the key may be
wrong/revoked, or the account may be out of tokens (get_usage tells you which).
The API key is sent in the request body, never in a URL, and is redacted from every error
message (HTTP, network and JSON-parse errors alike).
Development
See CONTRIBUTING.md for the full workflow and
docs/api-notes.md for API behaviour verified against a live account.
License
MIT
Related
