# News MCP Server

A FastMCP server that exposes news tools powered by the GNews API.

## What this project does

This server provides two MCP tools:

- `search_news(...)` to search articles by keyword and filters
- `top_headlines(...)` to fetch current top stories by category

## Requirements

- Python 3.14+
- `uv`
- A GNews API key

## Setup

1. Install dependencies

   ```bash
   uv sync
   ```

2. Create a `.env` file in the project root with your API key:

   ```env
   GNEWS_API_KEY=your_gnews_api_key_here
   ```

3. Start the server

   ```bash
   uv run python main.py
   ```

The server runs with the `streamable-http` transport.

## Available tools

### `search_news`

Search news articles with filters such as language, country, keywords, date range, and sorting.

Example:

```python
search_news(q="OpenAI", lang="en", country="us", max=5)
```

### `top_headlines`

Get top headlines for a category such as `general`, `business`, `technology`, `health`, and more.

Example:

```python
top_headlines(category="technology", country="us", max=5)
```

## Debugging with MCP Inspector

1. Start the Inspector:

   ```bash
   npx @modelcontextprotocol/inspector
   ```

2. Connect using the `streamable-http` transport.

3. Use the server URL:

   ```text
   http://127.0.0.1:8000/mcp
   ```

If your local port differs, adjust the URL accordingly.

## VS Code MCP configuration

You can connect this server to VS Code by adding a configuration similar to the following to your MCP settings:

```json
{
  "servers": {
    "news-mcp-server": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## Troubleshooting

- Make sure `GNEWS_API_KEY` is set correctly in your `.env` file.
- Confirm the server is running before connecting from the inspector or VS Code.
- If the inspector cannot connect, verify that the server URL includes `/mcp`.