Skip to main content

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.

SettingValue
URLhttps://mcp.gnews.io/
TransportStreamable HTTP
AuthenticationX-Api-Key header with your API key (sign up to get one)
Registryio.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​

Finds the articles that match a query. It works like the Search endpoint.

NameTypeRequiredDefaultDescription
qstringYesNoneWhat to search for, with the query syntax (exact phrases, parentheses, AND, OR, NOT)
langstringNoAny2-letter language code, for example en
countrystringNoAny2-letter country code of the source, for example us
maxintegerNo10Number of articles to return, from 1 to your plan's limit
in_fieldsstringNotitle,descriptionWhere to search, comma-separated: title, description, content
sortbystringNopublishedAtpublishedAt (most recent first) or relevance
date_fromstringNoNoneOldest publication date: YYYY-MM-DD or ISO 8601 (2026-10-01T08:30:00Z)
date_tostringNoNoneNewest publication date, same formats
pageintegerNo1Page number

top_headlines​

Returns the current top headlines of a category. It works like the Top Headlines endpoint.

NameTypeRequiredDefaultDescription
categorystringNogeneralgeneral, world, nation, business, technology, entertainment, sports, science, or health
langstringNoAny2-letter language code, for example en
countrystringNoAny2-letter country code, for example us
maxintegerNo10Number of articles to return, from 1 to your plan's limit
qstringNoNoneOptional query the headlines must match
date_fromstringNoNoneOldest publication date: YYYY-MM-DD or ISO 8601 (2026-10-01T08:30:00Z)
date_tostringNoNoneNewest publication date, same formats
pageintegerNo1Page 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.