<div align="center">

# BrunoSan AI News MCP Server

**Real-time AI news intelligence for AI agents · MCP-native · EU-hosted**

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Python 3.12](https://img.shields.io/badge/Python-3.12-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-00FFF0.svg)](https://modelcontextprotocol.io)
[![Hosted](https://img.shields.io/badge/Hosted-EU%20%C2%B7%20GDPR-2ecc71.svg)](https://brunosan.de/intelligence/)

</div>

---

## What this is

A Model Context Protocol server that exposes the BrunoSan AI News
intelligence layer to AI agents and MCP-compatible clients (Claude
Desktop, Cursor, n8n, custom agents).

```
88,000+   AI and tech articles indexed
10,500+   curated global sources
77,000+   tracked entities (companies · people · products · regions)
        9 deterministic, auditable tools
```

> *Snapshot: 2026-05-03 · Articles archive reaches back to January 2020 · Daily growing.*

## What this is not

This repository contains the **read-layer** that exposes the BrunoSan
news database as MCP tools. Article ingestion, source curation,
deterministic scoring, and clustering pipelines run upstream and
remain operated by DoWell UG.

If you want the data, the recommended path is the hosted service.
Self-hosting this server is supported but requires you to provide
your own news database.

## Use the hosted service

Free trial (50 calls, no card required) and paid tiers:
**<https://brunosan.de/mcp.html>**

Endpoint: `https://mcp.brunosan.de/mcp`

After subscribing, you receive an API key. Pass it as the `api_key`
parameter on every tool call. Works with any MCP-compatible client.

### Claude Desktop

Add to your `claude_desktop_config.json` (see [examples/claude_desktop_config.json](examples/claude_desktop_config.json)):

```json
{
  "mcpServers": {
    "brunosan-ai-news": {
      "url": "https://mcp.brunosan.de/mcp",
      "transport": "http"
    }
  }
}
```

Restart Claude Desktop. Ask: *"What are today's trending AI topics?"*

### Smithery

Listed and verified: <https://smithery.ai/server/@brunosan/global-ai-news>

## Self-host this server

For developers who want to point the server at their own news database,
or who want to extend the read-layer.

### Requirements

- Docker and Docker Compose
- A SQLite database with the BrunoSan news schema
- Python 3.12 if you prefer running without Docker

### Quick start with Docker

```bash
git clone https://github.com/DowellUG/brunosan-ai-news-mcp.git
cd brunosan-ai-news-mcp
cp .env.example .env

# Place your news SQLite DB at:
mkdir -p data
cp /path/to/your/brunosan_news.db data/

docker compose up -d
```

The MCP endpoint will be available at `http://localhost:8020/mcp`.

To connect from Claude Desktop locally, point the config URL at your
own host. To disable authentication entirely (development mode), set
`BRUNOSAN_AUTH_DB=""` in the environment.

### Run without Docker

```bash
pip install -r requirements.txt
export BRUNOSAN_NEWS_DB=/absolute/path/to/brunosan_news.db
export BRUNOSAN_AUTH_DB=""   # disable auth for local dev
python brunosan_news_mcp.py
```

## The nine tools

All tools are read-only, idempotent, and require an `api_key` parameter.

### Information tools

- **`news_search`** — Full-text search across all articles. Returns
  matched articles with title, teaser, source, URL, and publication
  date.

- **`news_get_entity`** — Profile of a company, person, product, or
  region. Returns recent articles and the entities most frequently
  co-mentioned alongside it.

- **`news_trending`** — Top topic clusters for a given day, ranked
  by burst score. Each cluster has a representative title, top
  entities, and counts.

- **`news_daily_digest`** — Full daily overview with statistics
  and top clusters. Designed for morning briefings and newsletter
  preparation.

- **`news_get_sources`** — Source statistics and database overview.
  Useful for transparency checks.

- **`news_search_entities`** — Discovery across known entities, with
  optional type filter (company, person, product, region).

### Signal tools

- **`news_signal_strength`** — Seven deterministic 0–100 scores per
  article: AI relevance, business relevance, Mittelstand relevance,
  regulation, risk, cost, operational. All computed without LLMs and
  reproducible.

- **`news_decision_maker_brief`** — Cluster ranking for a chosen role
  (CDO, CTO, CEO, Compliance) using a transparent composite formula:

  ```
  composite_score = burst_score
                  × (tier1_source_count + 1)
                  × (hard_numbers_count + 1)
                  × ai_relevance_score
  ```

  The formula is identical across roles; the role only filters which
  clusters are eligible. The output includes every input component so
  the score can be verified.

- **`news_risk_radar`** — Risk and compliance signals ranked by an
  open formula:

  ```
  combined_risk_score = (risk_signal_count    × 2)
                      + (compliance_signal_count × 3)
                      + (official_source_count   × 1)
  ```

  Returns clusters sorted by combined score with all three component
  counts visible for audit.

## Architecture

```
┌───────────────────┐       ┌──────────────────────┐       ┌─────────────────┐
│  MCP Client       │───────▶  This Server         │───────▶  News Database  │
│  (Claude/Cursor)  │  MCP  │  (read-only)         │ SQL   │  (read-only)    │
└───────────────────┘       └──────────────────────┘       └─────────────────┘
                                       │
                                       ▼
                            ┌──────────────────────┐
                            │  Auth (reference     │
                            │  or hosted version)  │
                            └──────────────────────┘
```

The server reads from `news_articles`, `daily_clusters`,
`daily_cluster_members`, `daily_cluster_evidence`,
`daily_cluster_entities`, `article_entities`, and
`article_fact_profile`. It writes only to the auth-key database
(call counters, when applicable).

## Configuration

| Variable | Default | Description |
|---|---|---|
| `BRUNOSAN_NEWS_DB` | `/data/brunosan_news.db` | Path to the news SQLite database. |
| `BRUNOSAN_AUTH_DB` | `/auth/api_keys.db` | Path to the auth key database. Set to empty string to disable auth. |
| `BRUNOSAN_HOST` | `0.0.0.0` | Bind host. |
| `BRUNOSAN_PORT` | `8020` | Bind port. |

## Production deployment notes

The hosted service uses Traefik for TLS termination and the multi-vertical
auth library (per-vertical key scoping, tier limits, billing integration)
which is operated separately and not in this repository.

For your own production deployment, terminate TLS with a reverse proxy
(Caddy, Traefik, nginx) in front of this container, which speaks plain
HTTP on port 8020.

## License

[Apache License 2.0](LICENSE) — see also [NOTICE](NOTICE) for attribution.

## Operated by

[**DoWell UG**](https://brunosan.de) · Hamburg, Germany

For partnerships, custom integrations, or workshop bookings:
**oliver@brunosan.de**

---

<sub>Built daily, in the EU. 🐾</sub>