# newspaper-mcp

An MCP server that exposes [newspaper4k](https://github.com/AndyTheFactory/newspaper4k)'s
news article discovery and extraction capabilities as tools for LLM agents.
Built with the official [MCP Python SDK v2](https://py.sdk.modelcontextprotocol.io/).

## Tools

| Tool                    | Description                                                                 |
| ------------------------ | ---------------------------------------------------------------------------- |
| `parse_article`          | Download and parse a single article (title, authors, text, images, NLP).    |
| `parse_articles`         | Download and parse multiple article URLs concurrently.                     |
| `discover_source`        | Crawl a news site's homepage for brand info, categories, feeds, articles.   |
| `list_source_articles`   | List article URLs/titles discovered on a source, with pagination.          |
| `search_news`            | Search Google News by keyword/topic/site/location (requires `gnews`).      |
| `extract_article_text`   | Fast text-only extraction from raw HTML or a URL, no metadata/NLP.         |
| `analyze_article`        | Download + run NLP: keywords with scores and an extractive summary.        |
| `get_source_categories`  | List a source's section/category URLs.                                     |
| `get_source_feeds`       | List a source's RSS/Atom feed URLs.                                        |

## Setup

This package depends on the local `newspaper4k` checkout at the repository
root (via `tool.uv.sources` in `pyproject.toml`), so it always uses the
in-development version of the library.

```bash
cd newspaper_mcp
uv sync
```

## Run

```bash
uv run newspaper-mcp          # stdio transport (default)
uv run mcp dev src/newspaper_mcp/server.py   # MCP Inspector
```

To add it to an MCP host (e.g. Claude Code, Claude Desktop), point the host
at `uv run --directory /path/to/newspaper_mcp newspaper-mcp` as a stdio
server.

## Notes

- `search_news` requires the optional `gnews` package, already pulled in via
  the `newspaper4k[gnews]` extra declared in `pyproject.toml`.
- NLP features (`nlp()`, keyword extraction, summarization) require `nltk`,
  pulled in via the `newspaper4k[nlp]` extra. On first use, `nltk` may need
  to download its `punkt` tokenizer data.
- All tools perform live network requests to the target news sites; there is
  no caching between calls.