newsapi-ai-mcp

MCP server for newsapi.ai (Event Registry): search news articles and events from ~150k sources worldwide — from Claude (Code, Desktop, claude.ai), Codex, OpenCode, Cursor or any other MCP client. Ships with an Agent Skill that teaches agents how to query the API well (and how to fall back to plain curl where no MCP is available).

Tools

Results are trimmed to compact JSON (snippets instead of full bodies, flattened labels) to save context; pass response_format: "raw" for the untouched API response.

Related MCP server: AI News MCP

Configuration

Instead of environment variables you can use a config file — handy for GUI apps, which on macOS don't see variables from ~/.zshrc:

mkdir -p ~/.config/newsapi-ai-mcp && chmod 700 ~/.config/newsapi-ai-mcp
echo '{"apiKey": "your-key", "maxDays": 31}' > ~/.config/newsapi-ai-mcp/config.json
chmod 600 ~/.config/newsapi-ai-mcp/config.json

Key lookup order: plugin settings → NEWSAPI_AI_KEY → config file. Empty values and unexpanded ${…} placeholders are skipped.

Claude Code: one-step plugin (MCP server + skill)

This repo is also a Claude Code plugin marketplace. The plugin installs the MCP server and the skill together:

/plugin install newsapi-ai --marketplace elcamino/newsapi-ai-mcp

(older Claude Code: /plugin marketplace add elcamino/newsapi-ai-mcp, then /plugin install newsapi-ai@elcamino)

During installation Claude Code shows a settings dialog:

Change them later with /plugin configure newsapi-ai@elcamino (or /plugin → Installed → newsapi-ai). From a shell: claude plugin install newsapi-ai@elcamino --config api_key=… --config max_days=31. Restart the session after changing settings.

Claude Cowork / desktop chat: these don't show plugin settings dialogs. The plugin still loads there; put the key into the config file (see Configuration) instead.

Install — local (stdio)

Alternatives to npx -y newsapi-ai-mcp: npx -y github:elcamino/newsapi-ai-mcp (latest main) or node /path/to/newsapi-ai-mcp/dist/index.js (after npm install in a checkout).

Claude Code

claude mcp add newsapi-ai -s user -e NEWSAPI_AI_KEY=your-key -- npx -y newsapi-ai-mcp

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "newsapi-ai": {
      "command": "npx",
      "args": ["-y", "newsapi-ai-mcp"],
      "env": { "NEWSAPI_AI_KEY": "your-key" }
    }
  }
}

Codex CLI — ~/.codex/config.toml

[mcp_servers.newsapi-ai]
command = "npx"
args = ["-y", "newsapi-ai-mcp"]
env = { NEWSAPI_AI_KEY = "your-key" }

OpenCode — opencode.json (project) or ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "newsapi-ai": {
      "type": "local",
      "command": ["npx", "-y", "newsapi-ai-mcp"],
      "environment": { "NEWSAPI_AI_KEY": "{env:NEWSAPI_AI_KEY}" },
      "enabled": true
    }
  }
}

Cursor / Windsurf / Cline / Zed / anything else: same command + args + env triple in that client's MCP config.

Install — remote (Streamable HTTP)

For claude.ai custom connectors, Claude mobile, or sharing one server across machines:

NEWSAPI_AI_KEY=your-key MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  npx -y newsapi-ai-mcp --http --host 0.0.0.0 --port 8787

• Endpoint: https://your-host/mcp (health check: /health). Stateless, POST only.

• Auth: Authorization: Bearer <MCP_AUTH_TOKEN>; clients that can't set headers (e.g. a claude.ai custom connector) can use https://your-host/mcp?token=<MCP_AUTH_TOKEN>.

• Optional per-client API key: header X-NewsAPI-Key overrides NEWSAPI_AI_KEY.

• Run it behind TLS (Caddy, Traefik, Cloudflare Tunnel).

Docker + Caddy:

docker compose up -d   # see docker-compose.yml, put NEWSAPI_AI_KEY / MCP_AUTH_TOKEN in .env

news-mcp.example.com {
  reverse_proxy newsapi-ai-mcp:8787
}

Then in claude.ai: Settings → Connectors → Add custom connector → URL https://news-mcp.example.com/mcp?token=….

Remote config for other clients, e.g. Claude Code:

claude mcp add --transport http newsapi-ai https://news-mcp.example.com/mcp --header "Authorization: Bearer …"

The skill

skills/newsapi-ai/ is a standard SKILL.md folder:

• Claude Code: comes with the plugin above; or copy to ~/.claude/skills/newsapi-ai/

• claude.ai / Desktop: zip the folder and upload it under Settings → Capabilities → Skills (claude.ai skills also sync into Claude Code sessions signed in with a claude.ai account)

• Codex / OpenCode / others with Agent Skills support: put it in the client's skills directory; otherwise paste it into AGENTS.md or the system prompt

Development

npm install
npm test        # builds, then runs an end-to-end test (stdio + HTTP) against a mock API

Releases: bump version in package.json and src/index.ts, push a tag vX.Y.Z — the GitHub workflow tests and publishes to npm (needs the NPM_TOKEN repo secret).

MIT License.