newsdata-mcp 0.1.0__tar.gz

newsdata_mcp-0.1.0/.dockerignore

@@ -0,0 +1,41 @@
+# Build context: the Dockerfile only COPYs pyproject.toml, uv.lock,
+# README.md, src/, and LICENSE. Everything else listed here is
+# excluded from the build context so `docker build` uploads less and
+# layer hashes stay stable when these change.
+
+# Python build / runtime artifacts
+__pycache__
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Tests, CI, editor config — not needed inside the image
+tests/
+.github/
+.vscode/
+.idea/
+
+# Local scratch / per-machine markers
+.codex
+temp.py
+.claude/
+
+# VCS / environment
+.git/
+.gitignore
+.env
+
+# Project docs not shipped in the image (README.md is needed by
+# Dockerfile and is NOT listed here).
+CLAUDE.md

newsdata_mcp-0.1.0/.env.example

@@ -0,0 +1,14 @@
+# NewsData.io credentials — copy this file to `.env` and fill in.
+NEWSDATA_API_KEY="your_newsdata_api_key_here"
+
+# Optional: request timeout in seconds (default: 30)
+# REQUEST_TIMEOUT=30
+
+# Optional: override the API base URL (e.g. for staging or a local mock)
+# NEWSDATA_BASE_URL=https://newsdata.io/api/1
+
+# Optional: retry policy for transient failures (network, 5xx, 429).
+# Defaults sleep ~62s total across 5 attempts (2s → 4s → 8s → 16s → 32s, capped at 60s).
+# NEWSDATA_MAX_RETRIES=5
+# NEWSDATA_RETRY_BACKOFF=2.0
+# NEWSDATA_RETRY_BACKOFF_MAX=60.0

newsdata_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies (runtime + dev)
+        run: uv sync --all-groups --frozen
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Type-check (mypy)
+        run: uv run mypy
+
+      - name: Test (pytest, unit only by default)
+        run: uv run pytest --cov=newsdata_mcp --cov-report=term-missing

newsdata_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,85 @@
+name: release
+
+# Tag-triggered: build sdist + wheel, publish to PyPI via Trusted
+# Publishing (OIDC, no API token), then create a GitHub Release with
+# auto-generated notes and the same artifacts attached.
+#
+# Requires a one-time PyPI Trusted Publisher config:
+#   PyPI project "newsdata-mcp" → Publishing → Add a new pending /
+#   trusted publisher with
+#     Owner:           newsdataapi
+#     Repository:      newsdata.io-mcp
+#     Workflow:        release.yml
+#     Environment:     pypi
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Show artifacts
+        run: ls -la dist/
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/newsdata-mcp
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

newsdata_mcp-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environment
+.venv/
+
+# Secrets
+.env
+
+# Tooling caches (mypy, pytest, ruff, coverage)
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Local-only files
+.codex
+temp.py
+CLAUDE.md
+.vscode/

newsdata_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

newsdata_mcp-0.1.0/Dockerfile

@@ -0,0 +1,57 @@
+# Multistage build: resolve and install with uv against the lockfile in
+# the builder, then copy the resulting venv into a minimal runtime stage.
+
+# ---------- Builder ----------
+FROM python:3.12-slim AS builder
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+# uv is a small Rust binary; pip-install it once in the builder.
+RUN pip install --no-cache-dir uv
+
+WORKDIR /app
+
+# Install dependencies first (without the project itself) so this layer
+# stays cached when only application source changes. LICENSE is needed
+# at build time because pyproject.toml declares `license = { file = ... }`.
+COPY pyproject.toml uv.lock README.md LICENSE /app/
+RUN uv sync --frozen --no-install-project --no-dev
+
+# Now copy source and install the project itself into the same venv.
+COPY src /app/src
+RUN uv sync --frozen --no-dev
+
+# ---------- Runtime ----------
+FROM python:3.12-slim AS runtime
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    REQUEST_TIMEOUT=30 \
+    PATH="/app/.venv/bin:$PATH"
+
+WORKDIR /app
+
+# Copy the populated venv + project source from the builder. LICENSE
+# is already inside /app from the builder stage.
+COPY --from=builder /app /app
+
+# Run as a non-root user.
+RUN useradd --create-home --uid 1000 app \
+    && chown -R app:app /app
+USER app
+
+EXPOSE 8000
+
+# TCP-level liveness probe; only meaningful for streamable-http transport.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+    CMD python -c "import socket; s=socket.socket(); s.settimeout(2); s.connect(('localhost',8000)); s.close()" || exit 1
+
+LABEL org.opencontainers.image.title="newsdata-mcp" \
+      org.opencontainers.image.description="MCP server for NewsData.io" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.source="https://github.com/newsdataapi/newsdata.io-mcp"
+
+ENTRYPOINT ["newsdata-mcp"]
+CMD ["--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]

newsdata_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NewsData.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

newsdata_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: newsdata-mcp
+Version: 0.1.0
+Summary: MCP server for the NewsData.io REST API (latest/archive/crypto/market news, source discovery, aggregate counts).
+Project-URL: Homepage, https://newsdata.io
+Project-URL: Documentation, https://newsdata.io/documentation
+Project-URL: Repository, https://github.com/newsdataapi/newsdata.io-mcp
+Project-URL: Issues, https://github.com/newsdataapi/newsdata.io-mcp/issues
+Author-email: "NewsData.io" <contact@newsdata.io>
+License: MIT License
+        
+        Copyright (c) 2026 NewsData.io
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,crypto,market,mcp,model-context-protocol,news,newsdata
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: mcp[cli]<2,>=1.27.0
+Requires-Dist: pydantic<3,>=2.7.0
+Requires-Dist: python-dotenv<2,>=1.2.2
+Description-Content-Type: text/markdown
+
+# NewsData MCP Server
+
+An MCP server for [NewsData.io](https://newsdata.io/documentation) that exposes real-time, historical, crypto, market, source-discovery, and aggregate-count tools to any MCP-compatible client.
+
+## 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 |
+
+All tools are read-only and idempotent; the MCP-protocol annotations let compatible clients (Claude Code, MCP Inspector, etc.) cache and parallelize calls.
+
+---
+
+## Installation
+
+The server is published on PyPI as [`newsdata-mcp`](https://pypi.org/project/newsdata-mcp/). The recommended path is to let your MCP client launch it via [`uvx`](https://docs.astral.sh/uv/guides/tools/) — no clone, no `uv sync`, no virtualenv to manage. The package is downloaded and cached on first launch.
+
+```bash
+# 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](#editor--client-integrations) below). Every client config uses the same launch command:
+
+```json
+"command": "uvx",
+"args": ["newsdata-mcp"]
+```
+
+For a local development checkout, see [Development](#development) below.
+
+### Configure environment
+
+Set `NEWSDATA_API_KEY` in your client config's `env` block (per the per-client examples below). When running the server outside an MCP client (development, Docker, `streamable-http`), use a `.env` file:
+
+```bash
+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_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.
+
+---
+
+## Docker
+
+```bash
+docker build -t newsdata-mcp .
+docker run --rm -p 8000:8000 -e NEWSDATA_API_KEY=your_newsdata_api_key newsdata-mcp
+```
+
+Run in stdio mode:
+
+```bash
+docker run --rm -i -e NEWSDATA_API_KEY=your_newsdata_api_key newsdata-mcp --transport stdio
+```
+
+Pass a `.env` file:
+
+```bash
+docker run --rm -p 8000:8000 --env-file .env newsdata-mcp
+```
+
+The image is a multistage build: dependencies are installed from `uv.lock` in a `python:3.12-slim` builder, then the resulting venv plus `LICENSE` is copied into a fresh `python:3.12-slim` runtime. The container runs as a non-root `app` user.
+
+---
+
+## 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):
+
+```json
+{
+  "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):
+
+```json
+{
+  "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:
+
+```bash
+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.
+
+---
+
+## Example Tool Calls
+
+```text
+get_latest_news(
+  q="((pizza OR burger) AND healthy)",
+  country=["us", "gb"],
+  language="en",
+  size=10
+)
+```
+
+```text
+get_archive_news(
+  q="ukraine war",
+  from_date="2025-01-01",
+  to_date="2025-01-31",
+  language="en"
+)
+```
+
+```text
+get_crypto_news(
+  coin=["btc", "eth"],
+  sentiment="positive"
+)
+```
+
+```text
+get_market_news(
+  symbol=["AAPL", "NVDA"],
+  country="us"
+)
+```
+
+```text
+get_news_sources(
+  language="en",
+  priority_domain="top"
+)
+```
+
+```text
+get_news_counts(
+  from_date="2024-01-01",
+  to_date="2024-01-31",
+  q="bitcoin",
+  interval="day"
+)
+```
+
+```text
+get_market_counts(
+  from_date="2024-01-01",
+  to_date="2024-03-31",
+  symbol=["AAPL", "NVDA"],
+  interval="hour"
+)
+```
+
+```text
+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.
+- 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](https://newsdata.io/documentation).
+
+---
+
+## Development
+
+```bash
+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`.
+
+## License
+
+MIT. See the [LICENSE](LICENSE) file.