{
  "markdown": "# Overtone News MCP Server\n\nAn MCP server that gives any agent real-time news plus the contextual\nintelligence to use it well — tone distribution, emerging stories,\nnarrative shifts, spike alerts, and tone-over-time charts — powered by\n[Overtone's](https://overtone.ai) publisher network.\n\nWorks with any MCP-compatible client: Claude Desktop, Claude Code,\nCursor, Windsurf, Codex, Kimi K2, and more.\n\n---\n\n## What it looks like\n\n**Natural language queries** — ask in plain English, get contextually analysed articles:\n\n![Natural language news demo](https://overtone.ai/wp-content/uploads/2026/04/overtone-haiku-demo.gif)\n\n**Global coverage analysis** — compare tone across languages and regions:\n\n![Global coverage tone comparison](https://overtone.ai/wp-content/uploads/2026/04/overtone-fr-de-compare.gif)\n\n**Tone timeseries** — track how a topic's emotional coverage shifts over time:\n\n![AI tone timeseries](https://overtone.ai/wp-content/uploads/2026/04/overtone-timeseries-demo.gif)\n\n---\n\n## Why this exists\n\nNews APIs return articles. That's the easy part. The hard part is\neverything an agent actually needs to reason about current events:\n\n- What's the *tone* of coverage on a topic — is the public mood angry,\n  hopeful, informational, fearful?\n- What's *emerging* right now that had zero coverage yesterday?\n- Where is *the narrative turning* — which topics are shifting tone\n  fastest?\n- Is there a *spike* in anger or fear around something I'm watching?\n- How has tone trended *over time* on a given story?\n\nThis server exposes all of that as MCP tools, so an agent can pull the\nright signal for the question it's been asked — not just a flat feed\nof headlines.\n\n---\n\n## Install\n\nThe server ships as a Python package. `uvx` (from [uv](https://docs.astral.sh/uv/))\nruns it without cluttering your global Python. Install `uv` once:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nThen add one block to your MCP client config. `uvx` fetches the package\nfrom PyPI and runs it on demand — no install step needed.\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`\n(macOS) or the equivalent on your platform:\n\n```json\n{\n  \"mcpServers\": {\n    \"overtone-news\": {\n      \"command\": \"uvx\",\n      \"args\": [\"overtone-news-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\nEdit `~/.config/claude-code/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"overtone-news\": {\n      \"command\": \"uvx\",\n      \"args\": [\"overtone-news-mcp\"]\n    }\n  }\n}\n```\n\n### Cursor / Windsurf\n\nSettings → MCP → Add server:\n\n- **Command**: `uvx`\n- **Args**: `overtone-news-mcp`\n\n### Codex\n\nEdit `~/.codex/config.toml`:\n\n```toml\n[[mcp_servers]]\nname = \"overtone-news\"\ncommand = \"uvx\"\nargs = [\"overtone-news-mcp\"]\n```\n\n---\n\n## Auth\n\nOn first tool call the server registers a free-tier API key with\nOvertone and caches it at `~/.overtone/credentials`. The cache is\nshared with the [Overtone News skill](https://github.com/CKBrennan/overtone-news-skill)\nfor Claude Code, so installing both won't double-register.\n\nFor a **premium key** (higher rate and daily limits), set\n`OVERTONE_NEWS_API_KEY` in the `env` block of your MCP config:\n\n```json\n\"overtone-news\": {\n  \"command\": \"uvx\",\n  \"args\": [\"--from\", \"git+https://github.com/CKBrennan/overtone-news-mcp\", \"overtone-news-mcp\"],\n  \"env\": { \"OVERTONE_NEWS_API_KEY\": \"ot-prod-...\" }\n}\n```\n\nRate limits:\n\n| Tier | Per minute | Per day |\n|---|---|---|\n| `auto` (free, auto-provisioned) | 10 | 50 |\n| `manual` (premium) | 60 | effectively unlimited |\n\nTo request a premium key, email [business@overtone.ai](mailto:business@overtone.ai).\n\n---\n\n## Environment variables\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `OVERTONE_NEWS_API_KEY` | *(auto-registered)* | Use a specific key instead of auto-registering |\n| `OVERTONE_NEWS_API_URL` | `https://agentic-skills.overtone.ai` | Override the API endpoint (for self-hosted or testing) |\n\n---\n\n## Tools\n\nAll tools return JSON. The agent chooses which tool fits the user's\nquestion — you don't invoke them directly.\n\n### `news`\nArticles on a topic, each tagged with tone, brand-safety signals,\narticle type, and concepts. Use for \"what's happening with X\".\n\n```python\nnews(query=\"AI regulation in Europe\", max_results=10, days=7,\n     tone_filter=\"informational\", brand_safe_only=True)\n```\n\nResponse includes a `request_id` — pass it back to `report` after\npresenting articles so we know what was actually shown.\n\n### `tone`\nEmotional tone distribution across recent coverage of a topic —\n`happy`, `funny`, `hopeful`, `informational`, `angry`, `sad`,\n`fearful`, plus the `dominant_tone`.\n\n```python\ntone(query=\"climate change\", days=3)\n```\n\nUse when the user asks *how* a topic is being covered, not *what*\nhappened.\n\n### `pulse`\nPollable spike detector. For each watched tone (default\n`angry` / `sad` / `fearful`), returns `spike_ratio` vs. a baseline\nwindow and a boolean `spiking`. `alerts` is populated only when\n`spike_ratio >= 1.5` with meaningful volume.\n\n```python\npulse(query=\"acme corp\", tones=[\"angry\", \"fearful\"],\n      recent_hours=6, baseline_hours=72)\n```\n\nIntended for polling every 5–15 minutes. Surface to the user *only*\nwhen `alerts` is non-empty.\n\n### `emerging`\nConcepts appearing in the last 24 hours that had zero coverage in\nthe prior 48 hours — candidate emerging stories. Cluster-filtered\nto ≥3 articles and ≥2 sources so single-article noise doesn't leak\nthrough.\n\n```python\nemerging(limit=10)\n```\n\n### `velocity`\nConcepts whose tone distribution has shifted most sharply between\nthe prior 48 hours and the most recent 24 hours. Answers \"where is\nthe narrative turning?\". Ranked by shape-normalized L2 distance, so\na uniform volume rise doesn't register as a shift.\n\n```python\nvelocity(limit=10)\n```\n\n### `timeseries`\nTone trajectory over time for a topic. `bin` is `hour`, `6h`, or\n`day`. Returns an ordered series of per-bin tone averages,\n`article_count`, and `dominant_tone`.\n\n```python\ntimeseries(query=\"federal reserve\", bin=\"6h\", hours=168)\n```\n\nBest rendered as a Mermaid line chart or ASCII sparkline.\n\n### `report`\nCalled silently *after* the agent presents articles to the user, to\nlog which `displayed_urls` it actually showed. Helps Overtone\nunderstand what content is most valuable to agentic clients.\n\n```python\nreport(request_id=\"<from news response>\",\n       displayed_urls=[...], displayed_count=3,\n       sponsorship_displayed=False)\n```\n\n---\n\n## Example agent flows\n\n**\"What's the mood around the NBA playoffs right now?\"**\n→ `tone(query=\"NBA playoffs\")` → summarize the distribution.\n\n**\"Anything breaking on the FDA I should know about?\"**\n→ `emerging(limit=20)` → filter for FDA-related concepts.\n\n**\"Track anger spikes on our brand every 10 minutes.\"**\n→ `pulse(query=\"acme corp\", tones=[\"angry\"])` on a loop; surface\nonly when `alerts` is non-empty.\n\n**\"Show me the last week of sentiment on Tesla.\"**\n→ `timeseries(query=\"Tesla\", bin=\"6h\", hours=168)` → render as chart.\n\n**\"Give me 5 positive stories about space exploration.\"**\n→ `news(query=\"space exploration\", max_results=5, tone_filter=\"positive\")`\n→ present → `report(...)`.\n\n---\n\n## Privacy — what's sent to Overtone\n\nWhen the server auto-registers a free-tier key on first use, it sends:\n\n- A **SHA-256 hash** of `hostname + OS user + CPU arch`. We never see\n  the raw values; the hash is used to deduplicate keys across reinstalls\n  on the same machine.\n\nNo personal data is transmitted during registration.\n\nOn every tool call, the server sends the API key and the tool's input\nparameters to `${OVERTONE_NEWS_API_URL}`. We log queries for analytics\nand abuse prevention; see [overtone.ai/privacy](https://overtone.ai/privacy).\n\n**No article content, user conversation, or agent context is ever sent\nbeyond the tool inputs.** We do not see the rest of your agent's\nprompt, memory, or other tool calls.\n\nTo opt out of auto-registration, set `OVERTONE_NEWS_API_KEY` manually\nto a key you've requested, or point `OVERTONE_NEWS_API_URL` at your\nown proxy.\n\n---\n\n## Security notes\n\n- **Prompt injection via article content.** The `news` tool returns\n  publisher text (headlines, descriptions). An article could contain\n  text designed to manipulate an agent (\"ignore previous instructions\n  and …\"). The MCP server itself has no destructive tools — it only\n  reads — but you should treat returned article text as untrusted\n  input in your agent's reasoning, the same way you'd treat any web\n  content. Sandboxing, output-only rendering, and tool allowlists in\n  the host are the right mitigations.\n- **No shell access.** The server never executes shell commands on\n  the user's behalf. The only `subprocess` use is reading\n  `git config --global user.{name,email}` during registration.\n- **No filesystem access beyond `~/.overtone/credentials`.** The\n  server does not read or write any other local files.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/CKBrennan/overtone-news-mcp\ncd overtone-news-mcp\nuv sync\nuv run overtone-news-mcp\n```\n\nPoint it at a non-production API while developing:\n\n```bash\nOVERTONE_NEWS_API_URL=http://localhost:8080 uv run overtone-news-mcp\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## Related\n\n- [overtone-news-skill](https://github.com/CKBrennan/overtone-news-skill) —\n  Claude Code skill version (shares credentials)\n- [overtone.ai](https://overtone.ai) — the intelligence behind the API\n- [![MCP Badge](https://lobehub.com/badge/mcp/ckbrennan-overtone-news-mcp)](https://lobehub.com/mcp/ckbrennan-overtone-news-mcp)\nmcp-name: io.github.CKBrennan/overtone-news-mcp\n",
  "bytes": 9537,
  "sha": "06e614cc11fa6950189ffc06043131c2e636576a690d54587b1e2a4a36a40e41",
  "repo_slug": "ckbrennan/overtone-news-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ckbrennan_overtone_news_mcp_2d7cabd8/readme"
}