Personal Assistant Server

A FastMCP server that exposes tools for news aggregation, financial market data, fitness tracking, Spotify music data, and email notifications — usable directly from Claude via the Model Context Protocol.

Also includes a daily newsletter that automatically emails a formatted digest of market data and news each morning via GitHub Actions.

Features

• News: Multi-source aggregation via NewsAPI and RSS (Times of Israel, Ynet, Hacker News, TechCrunch, The Verge, NPR, BBC)
• Finance: Real-time ETF/stock prices and weekly performance via Yahoo Finance
• Fitness: Strava integration for recent activities and weekly training summaries
• Music: Spotify integration for top tracks and top podcasts based on recent listening
• Email: Gmail SMTP notifications with HTML support
• Daily Newsletter: Scheduled HTML digest email sent every morning at 7:00 AM UTC

Tools Exposed via MCP

Tool	Description
send_email	Send an email via Gmail SMTP
fetch_news	Fetch top headlines from NewsAPI (optional query/category)
get_israeli_news	Latest news from Israeli RSS sources
get_tech_news	Latest tech news from RSS sources
get_daily_summary	Combined snapshot of all news + market data
get_etf_price	Current price and daily change for a ticker
get_market_snapshot	Multi-ticker market overview
get_recent_activities	Recent Strava activities
get_weekly_summary	Weekly Strava training summary
get_top_tracks	Top tracks from the last ~4 weeks via Spotify
get_top_podcasts	Top podcasts ranked by recent play frequency via Spotify

Setup

Prerequisites

• Python 3.12+
• uv package manager
• Gmail account with an App Password enabled
• NewsAPI API key
• (Optional) Strava API credentials
• (Optional) Spotify app credentials (see Spotify Setup)

Install

uv sync

Usage

As an MCP Server (Claude integration)

The .mcp.json file registers this server with Claude Code automatically. Once configured, the tools above are available directly in your Claude conversations.

To start the server manually:

uv run python server.py

For SSE transport (HTTP server on port 9005):

MCP_TRANSPORT=sse uv run python server.py

Send a daily newsletter manually

uv run python on_demand.py

With timeout protection

uv run python safe_runner.py

Inspect with MCP Inspector

npx @modelcontextprotocol/inspector uv run python server.py

Spotify Setup

Spotify requires OAuth — a one-time setup to obtain a refresh token.

1. Create a Spotify App

1. Go to the Spotify Developer Dashboard and create an app.
2. Under Edit Settings, add http://127.0.0.1:8888/callback as a Redirect URI.
3. Copy your Client ID and Client Secret into .env:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

2. Get a Refresh Token

Run the one-time authorization script:

uv run tools/spotify/get_refresh_token.py

This opens a browser tab for Spotify authorization. After you approve, the script prints your refresh token. Add it to .env:

SPOTIFY_REFRESH_TOKEN=your_refresh_token

The required OAuth scopes are user-top-read and user-read-recently-played.

Tools

Tool	Scope required	Description
get_top_tracks	user-top-read	Top tracks over the last ~4 weeks, ranked by Spotify
get_top_podcasts	user-read-recently-played	Top podcast shows ranked by episode play count in the last 50 recently-played items

Daily Newsletter (GitHub Actions)

The workflow at .github/workflows/daily-newsletter.yml runs every day at 7:00 AM UTC and sends an HTML email digest containing:

• Market snapshot with daily and weekly performance for key ETFs
• Israeli news highlights
• World news highlights
• Tech news highlights

Development

# Lint
uv run ruff check . --fix

# Run tests
uv run pytest

Tests cover internal utilities and data transformations. Mock tests for external APIs (NewsAPI, Yahoo Finance, Strava) are intentionally avoided — see .claude/CLAUDE.md for rationale.

Project Structure

├── server.py             # FastMCP server entry point
├── on_demand.py          # Daily newsletter generator
├── email_sender.py       # Gmail SMTP client
├── safe_runner.py        # Timeout-protected newsletter runner
├── logging_config.py     # Structured JSON logging
├── cost_estimate.py      # Monthly cloud cost estimator
├── tools/
│   ├── news/
│   │   ├── news.py       # RSS + NewsAPI aggregation
│   │   └── on_demand.py  # Manual newsletter trigger
│   ├── spotify/
│   │   ├── spotify.py          # Spotify API integration
│   │   ├── get_refresh_token.py # One-time OAuth token setup
│   │   └── on_demand.py        # Manual Spotify runner
│   ├── finance.py        # Yahoo Finance integration
│   ├── strava.py         # Strava API integration
│   └── daily_summary.py  # Aggregated daily snapshot
├── tests/                # Unit tests
└── .github/workflows/    # GitHub Actions