# Top News MCP Server

A remote MCP (Model Context Protocol) server deployed on Cloudflare Workers that exposes [NewsAPI.org](https://newsapi.org) as three tools for any MCP-compatible client (Claude Desktop, Claude.ai, MCP Inspector, etc.).

## Tools

| Tool | Description |
|------|-------------|
| `get_top_headlines` | Breaking news headlines by country, category, source, or keyword |
| `search_news` | Full-text search across 150,000+ sources with date ranges, sorting, domain filters |
| `list_sources` | Discover available news source IDs for use with the other tools |

## Deploy

### 1. Install dependencies

```bash
npm install
```

### 2. Set your NewsAPI secret

```bash
npx wrangler secret put NEWS_API_KEY
# Paste your API key when prompted
```

> **Important:** Never hardcode API keys in source files or `wrangler.jsonc`. The `wrangler secret` command stores the value encrypted at the edge.

### 3. Deploy

```bash
npx wrangler deploy
```

The server will be live at:

```
https://top-news-mcp.<your-account>.workers.dev/mcp
```

## Connect to Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "top-news": {
      "command": "npx",
      "args": ["mcp-remote", "https://top-news-mcp.<your-account>.workers.dev/mcp"]
    }
  }
}
```

Restart Claude Desktop after editing.

## Connect to Claude.ai

Use the MCP connector URL directly:

```
https://top-news-mcp.<your-account>.workers.dev/mcp
```

## Local Development

```bash
# Start local dev server
npm start

# In another terminal, test with MCP Inspector
npx @modelcontextprotocol/inspector@latest
# Enter http://localhost:8787/mcp
```

## Project Structure

```
top-news-mcp/
├── src/
│   ├── index.ts      # Worker entry point + routing
│   ├── mcp.ts        # McpAgent with tool definitions
│   ├── newsapi.ts    # NewsAPI v2 client + formatters
│   └── env.d.ts      # Env type (bindings + secrets)
├── wrangler.jsonc    # Cloudflare config
├── tsconfig.json
└── package.json
```

## Example Usage

Once connected, ask Claude:

- "What are today's top US headlines?"
- "Search for articles about AI regulation from the last week"
- "List all technology news sources in English"
- "Find BBC News headlines about climate change"