mcp-newsapi

MCP NewsAPI.ai

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):

Tool	Tokens per call
search_articles, get_article	1
search_events, get_event (info)	5
get_event (include_articles)	1
get_trending_concepts	10
suggest_*, get_usage	0

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

npm install -g @nubiia/mcp-newsapi

Install from source

git clone https://github.com/nubiia-dev/mcp-newsapi.git
cd mcp-newsapi
npm install
npm run build

Configuration

Environment Variables

Variable	Required	Description
NEWSAPI_AI_API_KEY	Yes	Your NewsAPI.ai API key (Dashboard). Secret — never commit it.
NEWSAPI_AI_MAX_TOKENS_PER_SESSION	No	Max NewsAPI.ai tokens this server may spend per session (until the server process restarts). Default 200.

export NEWSAPI_AI_API_KEY=your_newsapi_ai_key
export NEWSAPI_AI_MAX_TOKENS_PER_SESSION=200   # optional

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

{
  "mcpServers": {
    "newsapi": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-newsapi@latest"],
      "env": {
        "NEWSAPI_AI_API_KEY": "your_newsapi_ai_key",
        "NEWSAPI_AI_MAX_TOKENS_PER_SESSION": "200"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "newsapi": {
      "command": "node",
      "args": ["/path/to/mcp-newsapi/dist/index.js"],
      "env": {
        "NEWSAPI_AI_API_KEY": "your_newsapi_ai_key"
      }
    }
  }
}

Claude Code Configuration

claude mcp add newsapi --env NEWSAPI_AI_API_KEY=your_newsapi_ai_key -- npx -y @nubiia/mcp-newsapi@latest

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.

{ "prefix": "Telefónica", "types": ["org"], "count": 3 }

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.

{
  "concept_uris": ["http://en.wikipedia.org/wiki/Telefónica"],
  "lang": ["spa"],
  "date_start": "2026-10-01",
  "count": 5
}

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:

Tool(s)	Limit
search_articles, search_events, get_article, get_event	30 req/min
get_trending_concepts	20 req/min
suggest_*, get_usage	120 req/min
Everything else (default)	60 req/min

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

npm install
npm run build
npm test              # runs entirely against mocks — no network, no API key
npm run test:coverage
npm run lint

See CONTRIBUTING.md for the full workflow and docs/api-notes.md for API behaviour verified against a live account.

License

MIT

Related

• @nubiia/mcp-holded — MCP server for the Holded invoicing/accounting API.
• @nubiia/mcp-signaturit — MCP server for the Signaturit e-signature API.