MCP Server
This page shows you how to connect an AI assistant to GNews API through the hosted MCP server.
The GNews API MCP server lets AI assistants search news articles and get top headlines through the Model Context Protocol (opens in a new tab). It's hosted for you, so there's nothing to install: connect your client to it with your API key.
| Setting | Value |
|---|---|
| URL | https://mcp.gnews.io/ |
| Transport | Streamable HTTP |
| Authentication | X-Api-Key header with your API key (sign up to get one) |
| Registry | io.github.gnews-io/gnews in the official MCP Registry (opens in a new tab) |
Every tool call is one API request with your API key. It counts toward your daily quota, and your plan sets the articles per request, freshness, and historical data: see Article Availability.
Connect your client
Replace YOUR_API_KEY with the API key from your dashboard.
Claude Code
claude mcp add --transport http gnews_api https://mcp.gnews.io/ --header "X-Api-Key: YOUR_API_KEY"
Cursor
In ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"gnews": {
"url": "https://mcp.gnews.io/",
"headers": {
"X-Api-Key": "YOUR_API_KEY"
}
}
}
}
VS Code
In .vscode/mcp.json. VS Code asks for the API key the first time and stores it securely:
{
"inputs": [
{
"type": "promptString",
"id": "gnews-api-key",
"description": "GNews API key",
"password": true
}
],
"servers": {
"gnews": {
"type": "http",
"url": "https://mcp.gnews.io/",
"headers": {
"X-Api-Key": "${input:gnews-api-key}"
}
}
}
}
Gemini CLI
In ~/.gemini/settings.json:
{
"mcpServers": {
"gnews": {
"httpUrl": "https://mcp.gnews.io/",
"headers": {
"X-Api-Key": "YOUR_API_KEY"
}
}
}
}
Other clients
Any MCP client that supports the Streamable HTTP transport and custom headers can connect with the URL and header above.
Available tools
search
Finds the articles that match a query. It works like the Search endpoint.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
q | string | Yes | None | What to search for, with the query syntax (exact phrases, parentheses, AND, OR, NOT) |
lang | string | No | Any | 2-letter language code, for example en |
country | string | No | Any | 2-letter country code of the source, for example us |
max | integer | No | 10 | Number of articles to return, from 1 to your plan's limit |
in_fields | string | No | title,description | Where to search, comma-separated: title, description, content |
sortby | string | No | publishedAt | publishedAt (most recent first) or relevance |
date_from | string | No | None | Oldest publication date: YYYY-MM-DD or ISO 8601 (2026-10-01T08:30:00Z) |
date_to | string | No | None | Newest publication date, same formats |
page | integer | No | 1 | Page number |
top_headlines
Returns the current top headlines of a category. It works like the Top Headlines endpoint.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
category | string | No | general | general, world, nation, business, technology, entertainment, sports, science, or health |
lang | string | No | Any | 2-letter language code, for example en |
country | string | No | Any | 2-letter country code, for example us |
max | integer | No | 10 | Number of articles to return, from 1 to your plan's limit |
q | string | No | None | Optional query the headlines must match |
date_from | string | No | None | Oldest publication date: YYYY-MM-DD or ISO 8601 (2026-10-01T08:30:00Z) |
date_to | string | No | None | Newest publication date, same formats |
page | integer | No | 1 | Page number |
Both tools return the same JSON as the API: see JSON Response. The server also exposes the API
documentation as MCP resources (docs://gnews/cheatsheet, docs://gnews/search, docs://gnews/top-headlines).
Example prompts
- "What are today's top technology headlines in the United States, in English?"
- "Find English articles about the Federal Reserve from the last 3 days, most relevant first."
- "Summarize this morning's business news in the United States."
Privacy
The server is a proxy: it forwards your API key to GNews API with each request and doesn't store it. It records
anonymous usage statistics for each tool call (tool name, MCP client name and version, success or error, duration, and
the lang, country, category, max, page, and sortby parameters). Your API key is only recorded as a one-way
hash, and your search queries are never recorded.
Source code
The server is open source: see the gnews-io-mcp-server repository (opens in a new tab) on GitHub.