Newsdata.io MCP Server

The official MCP server for the Newsdata.io News API. It exposes real-time, historical, crypto, and market news — plus source discovery and aggregate counts — as tools for Claude Desktop, Claude Code, Cursor, Zed, Cline, VS Code Copilot, Windsurf, ChatGPT Desktop, and any other MCP-compatible AI assistant. Ask questions in natural language; the assistant calls the right tool and returns formatted news.

Example prompts

What's breaking in US politics today? Summarize the top 5 stories.

Find positive-sentiment crypto news about Bitcoin from the last 24 hours.

How many articles mentioned "interest rates" each day in January 2025?

Pull all market news on AAPL and NVDA, then list the headlines with publication dates.

Which English-language news sources cover both technology and business in the US?

The assistant maps these requests to the appropriate tool (get_latest_news, get_crypto_news, get_news_counts, get_market_news, get_news_sources, etc.) — no manual API calls needed.

---

Installation

The server is published on PyPI as newsdata-mcp. The recommended path is to let your MCP client launch it via uvx — no clone, no uv sync, no virtualenv to manage. The package is downloaded and cached on first launch.

# verify uvx + the server work end-to-end (optional)
uvx newsdata-mcp --version

Then add the server to your MCP client (see Editor & Client Integrations below). Every client config uses the same launch command:

"command": "uvx",
"args": ["newsdata-mcp"]

For a local development checkout, see Development below.

Configure environment

Set NEWSDATA_API_KEY in your client config's env block (per the per-client examples below). Get an API key at newsdata.io — the free tier is generous enough to evaluate. When running the server outside an MCP client (development, Docker, streamable-http), use a .env file:

cp .env.example .env
# then edit .env

Variable	Default	Notes
NEWSDATA_API_KEY	(required)	Newsdata.io credential. Missing key returns an error envelope on every call.
REQUEST_TIMEOUT	30	Per-request timeout in seconds.
NEWSDATA_BASE_URL	https://newsdata.io/api/1	Override for staging or a local mock.
NEWSDATA_MAX_RETRIES	5	Maximum attempts for transient failures (network, 5xx, 429).
NEWSDATA_RETRY_BACKOFF	2.0	Base for exponential backoff (base * 2^(attempt-1)). Seconds.
NEWSDATA_RETRY_BACKOFF_MAX	60.0	Cap on a single retry sleep, seconds.
NEWSDATA_WS_URL	wss://ws.newsdata.io/ws/event	Real-time endpoint used by stream_news.
NEWSDATA_WS_MAX_WAIT	120	Ceiling on stream_news's wait_seconds, in seconds.
NEWSDATA_INTEGRATION_KEY	(unset)	Used only by pytest -m integration. Without it, live-API tests skip.

All values are read at module import time; restart the server after changing them.

---

Editor & Client Integrations

The simplest way is to add the server to your MCP client's JSON config. Each client picks up the config on restart. All examples use uvx, which downloads + caches the published package — no local clone required.

Claude Code

Either edit ~/.claude/mcp.json (global) or .claude/mcp.json (per-project):

{
  "mcpServers": {
    "newsdata-mcp": {
      "command": "uvx",
      "args": ["newsdata-mcp"],
      "env": {
        "NEWSDATA_API_KEY": "your_newsdata_api_key"
      }
    }
  }
}

Then restart Claude Code.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) — same JSON block as above. Restart Claude Desktop.

Cursor

Create or edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally) — same JSON block. Restart Cursor; the server appears under Cursor Settings → MCP.

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace (or add an mcp key to user settings):

{
  "servers": {
    "newsdata-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["newsdata-mcp"],
      "env": {
        "NEWSDATA_API_KEY": "your_newsdata_api_key"
      }
    }
  }
}

Reload VS Code. Picked up by Copilot Chat in agent mode.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json — same JSON block as the Claude Code example. Restart Windsurf.

ChatGPT Desktop (OpenAI)

Run the server in HTTP mode locally:

NEWSDATA_API_KEY=your_key uvx newsdata-mcp \
  --transport streamable-http --host 127.0.0.1 --port 8000

Then in ChatGPT → Settings → Connectors → Add custom connector, register http://127.0.0.1:8000/mcp as the connector endpoint.

---

Available Tools

Tool	Endpoint	Description
get_latest_news	/api/1/latest	Recent and breaking news (last 48h)
get_archive_news	/api/1/archive	Historical news, filterable by from_date / to_date
get_crypto_news	/api/1/crypto	Crypto and blockchain-focused coverage
get_market_news	/api/1/market	Stock, financial, and market-related news
get_news_sources	/api/1/sources	Source discovery by country, category, or language
get_news_counts	/api/1/count	Aggregate article counts over a date range (hour / day buckets or single all total)
get_crypto_counts	/api/1/crypto/count	Aggregate crypto article counts over a date range
get_market_counts	/api/1/market/count	Aggregate market article counts over a date range
register_realtime_query	/api/1/websocket/register	Register a standing real-time query, returns a registration_id
list_realtime_queries	/api/1/websocket/fetch	List the account's registered real-time queries
delete_realtime_query	/api/1/websocket/delete	Delete a registered real-time query
stream_news	wss://ws.newsdata.io/ws/event	Collect real-time articles for a registered query (below)

The eight REST news tools are read-only and idempotent; the MCP-protocol annotations let compatible clients (Claude Code, MCP Inspector, etc.) cache and parallelize calls. register_realtime_query and delete_realtime_query are annotated as mutating (the latter destructive), since they create and remove server-side state.

---

Real-time news (WebSocket)

Real time is a two-step flow: register a standing query once, then collect from it as often as you like.

register_realtime_query(
  q="bitcoin",
  language="en"
)
→ registration_id: a1b2c3d4e5f6

stream_news(
  registration_id="a1b2c3d4e5f6",
  max_articles=10,
  wait_seconds=30
)

register_realtime_query takes the familiar filter parameters (q, country, language, domain, …). There are no date or paging filters — a registered query matches news as it is published. Registering identical filters twice answers Error (HTTP 409); call list_realtime_queries first to recover the existing id.

Why stream_news is bounded

MCP tools are request/response, so an open-ended stream cannot be a tool. stream_news listens on a live connection and returns as soon as either max_articles have arrived or wait_seconds elapses — whichever comes first. It always returns within wait_seconds.

Every reply states why it stopped, so the model can act on it:

stopped_because	Meaning
max_articles	Hit the cap — there may be more waiting
timeout	The window elapsed; a 0 count means the feed was simply quiet
connection_closed	The server ended the feed; returns whatever was collected

Call it again to keep listening — the registration stays alive between calls. An empty result is normal for a narrow query and does not mean anything failed.

Bounds: max_articles is clamped to 1–50, wait_seconds to 1–NEWSDATA_WS_MAX_WAIT (120 by default).

The server always accepts the handshake and then closes with code 1008 when the connection is refused, carrying one of three reasons: invalid credentials or registration not found, api limit reached, or device limit reached (more than 5 devices on one registration_id). Those return an Error and are not retried. Every other close code — including 1013 (send timeout) — is transient and surfaces as stopped_because: connection_closed with whatever was collected.

Cost. Each delivered article consumes 1 API credit per connected device. A broad query over a long window can burn credits quickly — keep max_articles no higher than you need.

---

Example Tool Calls

get_latest_news(
  q="((pizza OR burger) AND healthy)",
  country=["us", "gb"],
  language="en",
  size=10
)

get_archive_news(
  q="ukraine war",
  from_date="2025-01-01",
  to_date="2025-01-31",
  language="en"
)

get_crypto_news(
  coin=["btc", "eth"],
  sentiment="positive"
)

get_market_news(
  market_id=["AAPL", "NVDA"],
  country="us"
)

get_news_sources(
  language="en",
  priority_domain="top"
)

get_news_counts(
  from_date="2024-01-01",
  to_date="2024-01-31",
  q="bitcoin",
  interval="day"
)

get_market_counts(
  from_date="2024-01-01",
  to_date="2024-03-31",
  market_id=["AAPL", "NVDA"],
  interval="hour"
)

get_latest_news(
  q="elections",
  sentiment="positive",
  sentiment_score=70
)

Notes on parameter shapes:

• CSV-style filters accept either a Python list (preferred) or a comma-separated string.
• Boolean flags accept True/False or 1/0.
• timeframe accepts an integer for hours (e.g. 24) or a string with m suffix for minutes (e.g. 90m).
• interval (count tools only) accepts hour, day, or all (all returns a single aggregate count instead of buckets).
• sentiment_score is a 0–100 minimum confidence percentage and requires sentiment to also be set — e.g. sentiment="positive", sentiment_score=70 returns only articles whose positive-sentiment score is at least 70.

---

Notes

• Latest, crypto, and market endpoints return recent coverage — typically up to 48 hours.
• Free plan results are delayed relative to paid plans.
• Result size is capped by plan tier: commonly 10 results on free, up to 50 on paid plans.
• The count endpoints return aggregate buckets (one per interval slot) rather than article content.
• Real-time coverage needs a plan with WebSocket access; without it stream_news returns Error: invalid credentials or registration not found.
• Real-time articles are billed per delivered article, per connected device.
• Every tool returns plain text (the MCP-protocol return type). Errors come back as Error (HTTP 4xx): … with the status code and a friendly message; HTTP 429 errors include a retry after Ns hint when the upstream Retry-After header was parseable.

Full API reference: https://newsdata.io/documentation. Machine-readable contract: OpenAPI 3.1 spec.

---

Docker

For HTTP-mode deployments (e.g. behind a reverse proxy, or backing the ChatGPT Desktop connector):

docker build -t newsdata-mcp .
docker run --rm -p 8000:8000 -e NEWSDATA_API_KEY=your_newsdata_api_key newsdata-mcp

The image is a multistage build on python:3.12-slim and runs as a non-root user — see the Dockerfile for details.

---

Development

git clone https://github.com/newsdataapi/newsdata.io-mcp.git
cd newsdata.io-mcp
uv sync --all-groups                                       # install runtime + dev deps

uv run pytest                                              # unit tests only (default)
NEWSDATA_INTEGRATION_KEY=<key> uv run pytest -m integration  # live-API tests
uv run pytest --cov=newsdata_mcp --cov-report=term-missing  # with coverage
uv run ruff check src/ tests/
uv run mypy

CI (.github/workflows/ci.yml) runs the same four commands on every push/PR to main.

Releasing

1. Bump __version__ in src/newsdata_mcp/__init__.py.
2. Commit and tag: git tag vX.Y.Z && git push --tags.
3. .github/workflows/release.yml builds the sdist + wheel, publishes to PyPI via Trusted Publishing (no token), and creates a GitHub Release with auto-generated notes.

One-time PyPI setup: configure a Trusted Publisher on the newsdata-mcp project pointing at newsdataapi/newsdata.io-mcp, workflow release.yml, environment pypi.

---

Related libraries

Official Newsdata.io clients for direct REST access (no MCP layer):

Language / Runtime	Repo
Python	newsdataapi/python-client (PyPI)
Node.js	newsdataapi/newsdata-nodejs-client (npm)
React (hooks)	newsdataapi/newsdata-reactjs-client (npm)
PHP	newsdataapi/php-client (Packagist)
Java	newsdataapi/newsdata-java-sdk (Maven Central)
.NET	newsdataapi/newsdata-dotnet-sdk (NuGet)
Go	newsdataapi/newsdata-go-client (pkg.go.dev)
Dart / Flutter	newsdataapi/newsdata-flutter-client (pub.dev)

Also see free news datasets for ML / NLP work.

License

MIT. See the LICENSE file.