MarketBrief

Turn 40+ data sources into a daily Wall Street-style market briefing — delivered to your Telegram, automatically.

MarketBrief is an open-source framework that fetches real-time market data, aggregates news from 40+ RSS feeds, and uses Claude AI to generate structured analyst-grade reports. Think of it as your personal Bloomberg terminal distilled into a daily briefing.

Every morning at 7:00 AM, you wake up to this in Telegram:

  "Rates rise, equities capsize"

  TODAY'S FOCUS:
  - CPI 08:30 ET — beat eases Fed, miss reprices June cut
  - Gold $3,100 support — break below = safe-haven bid fading
  - Trump tariff speech 14:00 ET — new China tariffs trigger risk-off

  4 analyst-grade issues with source citations...
  Positioning table (OW/UW/MW)...
  Categorized news digest with 30+ items...
  Economic calendar with 10+ events...

What Problem Does This Solve?

If you're a retail investor, crypto trader, or market enthusiast, you probably:

• Check 5-10 websites every morning for market updates
• Miss important economic data releases
• Lack a systematic way to connect dots across asset classes
• Wish you had an analyst writing you a daily briefing

MarketBrief automates all of this. It pulls data from official sources (Fed, SEC, FRED, ECB), market data providers (Yahoo Finance, CoinGecko), and 40+ news feeds — then uses Claude AI to synthesize everything into a structured briefing with specific price levels, source citations, and actionable positioning.

How It Works

                 YOU CONFIGURE                          IT FETCHES
           ┌─────────────────────┐            ┌──────────────────────┐
           │  portfolio.json     │            │  Yahoo Finance       │
           │  - your holdings    │            │  FRED (official)     │
           │  - interest areas   │            │  CoinGecko           │
           │                     │            │  SoSoValue (ETF)     │
           │  dashboard.json     │            │  Frankfurter (ECB)   │
           │  - assets to track  │            │  40+ RSS feeds       │
           │                     │            │  Forex Factory       │
           │  feeds.json         │            │  MyFXBook            │
           │  - news sources     │            └──────────┬───────────┘
           └─────────┬───────────┘                       │
                     │                                   │
                     ▼                                   ▼
           ┌─────────────────────────────────────────────────────────┐
           │              Claude AI (2-stage pipeline)               │
           │                                                         │
           │  Stage 1: Pre-flight Editorial Analysis                 │
           │  → Identifies market regime (risk-on/off/rotation)      │
           │  → Groups news into narrative threads                   │
           │  → Kills 30-50% of noise items                          │
           │                                                         │
           │  Stage 2: Structured Report Generation                  │
           │  → 4-issue analysis (what/reaction/contradiction/view)  │
           │  → Source-cited positioning table                        │
           │  → Categorized news digest                              │
           │  → Economic calendar with impact scoring                │
           └─────────────────────┬───────────────────────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
              ┌──────────┐ ┌──────────┐ ┌──────────┐
              │ Telegram  │ │  Feishu  │ │ Terminal │
              │ (HTML+PDF)│ │  (Card)  │ │  (JSON)  │
              └──────────┘ └──────────┘ └──────────┘

No AI key? No problem. Without ANTHROPIC_API_KEY, MarketBrief still outputs a complete data-only report: market snapshot, news feed, economic calendar — just without the AI commentary.

Quick Start

1. Clone and install

git clone https://github.com/yukipanpan/marketbrief.git
cd marketbrief
pip install -e .

2. Configure

cp config/portfolio.example.json config/portfolio.json
cp config/dashboard.example.json config/dashboard.json
cp config/feeds.example.json config/feeds.json
cp .env.example .env

Edit .env with your API keys:

# Required for AI analysis (skip for data-only mode)
ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Optional — enhances data coverage
FRED_API_KEY="your-fred-key"              # Free at https://fred.stlouisfed.org/docs/api/api_key.html
SOSOVALUE_API_KEY="your-sosovalue-key"    # ETF flow data

# Optional — delivery channels
TELEGRAM_BOT_TOKEN="your-bot-token"       # Create at https://t.me/BotFather
TELEGRAM_CHAT_ID="your-chat-id"

3. Run

# Data-only mode (no AI key needed, free)
marketbrief generate --no-ai

# Full AI-powered report
marketbrief generate --output json

# Fetch specific data
marketbrief fetch market      # Live prices: equities, FX, commodities, crypto
marketbrief fetch news        # Aggregated news from 40+ feeds
marketbrief fetch calendar    # Economic calendar (Forex Factory + FRED)
marketbrief fetch crypto      # BTC, ETH, SOL prices from CoinGecko
marketbrief fetch etf         # BTC/ETH spot ETF flows from SoSoValue
marketbrief fetch fred        # Official US economic data (CPI, GDP, NFP...)

What You Can Customize

This is a template framework, not a finished product. Everything is designed to be modified:

Assets & Portfolio (config/portfolio.json)

Track whatever you care about. The default is US-focused, but you can:

{
  "holdings": [
    {"name": "Nikkei 225 ETF", "ticker": "EWJ", "category": "Japan Equities"},
    {"name": "Copper Futures", "ticker": "HG=F", "category": "Industrial Metals"},
    {"name": "Bitcoin", "ticker": "BTC-USD", "category": "Crypto"}
  ],
  "interest_areas": ["Semiconductors", "Uranium", "Japan"],
  "focus_regions": ["Japan", "US", "EU"]
}

Dashboard (config/dashboard.json)

Add or remove any asset that Yahoo Finance supports:

{
  "equities": [
    {"label": "Nikkei 225", "yf": "^N225"},
    {"label": "FTSE 100",  "yf": "^FTSE"},
    {"label": "DAX",       "yf": "^GDAXI"}
  ],
  "crypto_ids": ["bitcoin", "ethereum", "solana", "dogecoin"]
}

News Sources (config/feeds.json)

Add any RSS feed. Organize by category for smart filtering:

{
  "feeds": [
    {"name": "my_niche_blog", "category": "research", "url": "https://example.com/feed.xml"},
    {"name": "industry_news", "category": "markets",  "url": "https://industry.com/rss"}
  ]
}

Categories matter: government and geopolitics feeds are never truncated. macro and ai_tech feeds get a 7-day lookback (vs 36 hours for news).

AI Analysis Style (config/prompts/)

The Claude prompts are fully editable. You can:

• Change the output language (English, Chinese, or mixed)
• Adjust the number of analysis issues (default: 4)
• Modify the analyst voice (assertive sell-side vs neutral)
• Add custom analysis frameworks
• Change the positioning stance options

Use Cases & Ideas

MarketBrief is a starting point. Here's what you could build with it:

MCP Server

MarketBrief can run as an MCP server, letting any AI assistant (Claude Desktop, Claude Code, etc.) call market data tools directly.

pip install marketbrief[mcp]
python -m marketbrief.mcp_server

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "marketbrief": {
      "command": "python",
      "args": ["-m", "marketbrief.mcp_server"],
      "env": {"FRED_API_KEY": "your-key"}
    }
  }
}

7 Available Tools

Most tools work without any API key — only generate_report needs Anthropic.

Automated Delivery (GitHub Actions)

Run MarketBrief on a schedule — no server needed:

1. Copy the workflow template:

   mkdir -p .github/workflows
   cp workflows/morning_report.yml.template .github/workflows/morning_report.yml
   

2. Add secrets in your GitHub repo (Settings → Secrets → Actions):

   • ANTHROPIC_API_KEY
   • TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID
   • FRED_API_KEY (optional)

3. Adjust the cron schedule for your timezone (see workflows/README.md).

4. Push — reports will be generated and delivered automatically.

Data Sources

Project Structure

marketbrief/
├── src/marketbrief/
│   ├── core/
│   │   ├── config.py       # Unified config: JSON + env vars
│   │   ├── types.py        # Pydantic models for all data
│   │   ├── analysis.py     # Claude AI 2-stage pipeline
│   │   └── pipeline.py     # Main orchestrator
│   ├── fetchers/            # 6 data source modules
│   ├── renderers/           # HTML, Telegram, PDF, Markdown
│   ├── delivery/            # Telegram, Feishu, stdout
│   └── skills/              # Trading analysis modules
├── config/                  # Customizable JSON configs + prompts
├── mcp_server/              # MCP Server (7 tools)
├── claude_skill/            # Claude Code Skill definition
└── workflows/               # GitHub Actions templates

Contributing

PRs welcome! Some areas where contributions would be especially valuable:

• New fetchers: Add data sources (e.g., Binance, TradingView, Alpha Vantage)
• Renderers: Improve HTML/PDF output, add new formats (Slack, Discord, email)
• Trading skills: Port regime detector and breadth analyzer
• Localization: Prompts for other languages (Japanese, Korean, Spanish)
• Tests: Unit tests for fetchers and the analysis pipeline

License

MIT — use it however you want.