# Fed Speech MCP
An MCP (Model Context Protocol) server that retrieves, parses, and analyzes speeches and testimonies from major Federal Reserve officers.
---
## Features
- 📡 **RSS Feed Discovery** - Automatically discovers new speeches from Fed RSS feeds
- 🔍 **Index Page Scanning** - Backfill capability by scanning yearly index pages
- 📝 **Smart Parsing** - Extracts metadata, speaker info, and clean text from Fed HTML pages
- 📊 **Feature Extraction** - Detects topics (inflation, rates, labor market, etc.)
- ⚖️ **Importance Scoring** - Rule-based scoring for market relevance
- 💾 **JSON Storage** - Persistent storage with deduplication
- 🔌 **MCP Interface** - Full MCP compatibility for AI assistants
## Covered Content
### Speakers
- Chair of the Federal Reserve
- Vice Chair of the Federal Reserve
- Federal Reserve Governors
### Content Types
- Speeches
- Congressional Testimony
- Prepared Remarks
---
## Installation
### Prerequisites
- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/) package manager
**Install uv** (if you don't have it):
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Install the Project
```bash
cd fed-speech-mcp
# Create virtual environment and install
uv sync
```
That's it! The virtual environment is created and all dependencies are installed.
---
## 🚀 Quick Start: Test Locally in 5 Minutes
Want to see the MCP tools in action before connecting to an AI? Follow these steps:
### Step 1: Install
```bash
cd fed-speech-mcp
uv sync
```
### Step 2: Fetch Speeches from Fed Website
```bash
uv run python scripts/test_local.py refresh --limit 5
```
You'll see output like:
```
🔄 REFRESHING SPEECHES FROM FED WEBSITE
==================================================
📡 Discovering documents via RSS feeds...
Found 20 document(s)
[1/5] Processing: Governor Bowman's Speech on Banking...
✅ Fetched 45231 bytes
✅ Parsed: Michelle W. Bowman - speech
✅ Normalized: fed-speech-a1b2c3d4e5f6
✅ Saved (NEW)
...
✅ REFRESH COMPLETE
Discovered: 5
New: 5
Total in storage: 5
```
### Step 3: Explore the Data
**View latest speeches:**
```bash
uv run python scripts/test_local.py latest --limit 3
```
Output:
```
📰 LATEST SPEECHES
==================================================
Found 3 speech(es):
1. Speech on Monetary Policy and the Economic Outlook
📅 2024-12-15
👤 Jerome H. Powell (Chair)
📄 speech | 2500 words
⭐ high (0.85)
🏷️ Topics: inflation, rates, labor
🔗 https://federalreserve.gov/...
🆔 fed-speech-abc123
```
**Search by keyword:**
```bash
uv run python scripts/test_local.py search --query "inflation"
```
**Filter by speaker:**
```bash
uv run python scripts/test_local.py speaker --name "Powell"
uv run python scripts/test_local.py speaker --role "Chair"
```
**Get full speech content:**
```bash
uv run python scripts/test_local.py get --doc-id fed-speech-abc123
```
**View statistics:**
```bash
uv run python scripts/test_local.py stats
```
### Step 4: Run All Tests
```bash
uv run python scripts/test_local.py all
```
This runs a complete test suite: refresh → stats → latest → search → filter → get.
### Available Test Commands
| Command | Description | Example |
|---------|-------------|---------|
| `refresh` | Fetch new speeches | `--limit 5`, `--include-index` |
| `latest` | Show latest speeches | `--limit 10`, `--since 2024-01-01` |
| `search` | Search by keyword | `--query "inflation"` |
| `speaker` | Filter by speaker | `--name "Powell"`, `--role "Chair"` |
| `type` | Filter by doc type | `--doc-type testimony` |
| `get` | Get full speech | `--doc-id fed-speech-xxx` |
| `stats` | Show statistics | (no options) |
| `all` | Run all tests | (no options) |
---
## Using with AI Assistants
### Platform Compatibility Overview
| Platform | MCP Support | Setup Method |
|----------|-------------|--------------|
| **Claude Desktop** | ✅ Native | Direct MCP integration |
| **Cursor IDE** | ✅ Native | Direct MCP integration |
| **ChatGPT** | ⚠️ Via API | HTTP API wrapper + Custom GPT |
| **Google Gemini** | ⚠️ Via API | HTTP API wrapper + Google AI Studio |
| **Other AI Tools** | ⚠️ Via API | HTTP API wrapper |
---
## Step-by-Step: Claude Desktop
Claude Desktop has native MCP support. This is the easiest setup.
### Step 1: Install the Package
```bash
cd fed-speech-mcp
uv sync
```
### Step 2: Locate Claude Desktop Config
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
### Step 3: Add MCP Server Configuration
Edit `claude_desktop_config.json`:
```json
{
"mcpServers": {
"fed-speech": {
"command": "uv",
"args": ["run", "fed-speech-mcp"],
"cwd": "/path/to/fed-speech-mcp"
}
}
}
```
> **Note**: Replace `/path/to/fed-speech-mcp` with your actual installation path.
### Step 4: Restart Claude Desktop
Close and reopen Claude Desktop. You should see the Fed Speech tools available.
### Step 5: Start Using
Ask Claude things like:
- *"Refresh the Fed speeches and show me the latest ones"*
- *"What did Chair Powell say about inflation recently?"*
- *"Show me all testimony from 2024"*
---
## Step-by-Step: Cursor IDE
Cursor IDE also supports MCP natively.
### Step 1: Install the Package
```bash
cd fed-speech-mcp
uv sync
```
### Step 2: Open Cursor Settings
1. Open Cursor IDE
2. Go to **Settings** (⌘+, on macOS, Ctrl+, on Windows)
3. Search for "MCP" or navigate to **Features → MCP Servers**
### Step 3: Add MCP Server
Click "Add MCP Server" and configure:
```json
{
"name": "fed-speech",
"command": "uv",
"args": ["run", "fed-speech-mcp"],
"cwd": "/path/to/fed-speech-mcp"
}
```
### Step 4: Enable and Use
Toggle the server on. You can now use Fed Speech tools in Cursor's AI chat.
---
## Step-by-Step: ChatGPT (Custom GPT)
ChatGPT doesn't support MCP natively, but you can use the HTTP API wrapper.
### Step 1: Install the Package
```bash
cd fed-speech-mcp
uv sync
```
### Step 2: Start the HTTP API Server
```bash
uv run fed-speech-http
```
The server runs at `http://localhost:8000` by default.
### Step 3: Expose to Internet (Required for ChatGPT)
Use a tunneling service like ngrok:
```bash
# Install ngrok: https://ngrok.com/download
ngrok http 8000
```
Copy the public URL (e.g., `https://abc123.ngrok.io`).
### Step 4: Create a Custom GPT
1. Go to [ChatGPT](https://chat.openai.com)
2. Click your profile → **My GPTs** → **Create a GPT**
3. In the **Configure** tab:
- **Name**: "Fed Speech Analyst"
- **Description**: "Analyzes Federal Reserve speeches and testimonies"
- **Instructions**:
```
You are a Federal Reserve speech analyst. Use the available actions to:
1. Fetch latest speeches with get_latest_speeches
2. Search speeches by speaker, type, or keywords
3. Analyze speech content for market-relevant insights
Always refresh speeches first if the user asks about recent content.
```
4. Click **Create new action** and import the OpenAPI schema:
```yaml
openapi: 3.0.0
info:
title: Fed Speech API
version: 1.0.0
servers:
- url: https://your-ngrok-url.ngrok.io
paths:
/speeches/latest:
get:
operationId: getLatestSpeeches
summary: Get latest Fed speeches
parameters:
- name: limit
in: query
schema:
type: integer
default: 10
- name: since_date
in: query
schema:
type: string
responses:
'200':
description: List of speeches
/speeches/search:
get:
operationId: searchSpeeches
summary: Search speeches by keyword
parameters:
- name: query
in: query
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 10
responses:
'200':
description: Search results
/speeches/{doc_id}:
get:
operationId: getSpeech
summary: Get a specific speech
parameters:
- name: doc_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Speech details
/speeches/refresh:
post:
operationId: refreshSpeeches
summary: Fetch new speeches from Fed website
responses:
'200':
description: Refresh result
```
### Step 5: Save and Use
Save your Custom GPT. Now you can ask it questions about Fed speeches!
---
## Step-by-Step: Google Gemini
Google Gemini can use the HTTP API via Google AI Studio or API.
### Step 1: Start the HTTP API Server
```bash
cd fed-speech-mcp
uv sync
uv run fed-speech-http
```
### Step 2: Expose to Internet
```bash
ngrok http 8000
```
### Step 3: Use with Google AI Studio
1. Go to [Google AI Studio](https://aistudio.google.com)
2. Create a new prompt or chat
3. In your system instructions, include:
```
You have access to a Fed Speech API at https://your-ngrok-url.ngrok.io
Available endpoints:
- GET /speeches/latest?limit=10 - Get latest speeches
- GET /speeches/search?query=inflation - Search speeches
- GET /speeches/{doc_id} - Get specific speech
- POST /speeches/refresh - Fetch new speeches
- GET /speeches/by-speaker?name=Powell - Filter by speaker
- GET /speeches/by-type?doc_type=testimony - Filter by type
When users ask about Fed speeches, use these endpoints to fetch data.
Format responses clearly with speaker names, dates, and key points.
```
### Step 4: Use Function Calling (Advanced)
For programmatic use with Gemini API:
```python
import google.generativeai as genai
import requests
# Configure Gemini
genai.configure(api_key="YOUR_API_KEY")
# Define tools for Gemini
tools = [
{
"function_declarations": [
{
"name": "get_latest_speeches",
"description": "Get the latest Federal Reserve speeches",
"parameters": {
"type": "object",
"properties": {
"limit": {"type": "integer", "description": "Max speeches to return"}
}
}
},
{
"name": "search_speeches",
"description": "Search Fed speeches by keyword",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"]
}
}
]
}
]
model = genai.GenerativeModel('gemini-pro', tools=tools)
# Handle function calls
def handle_function_call(fn_name, args):
base_url = "http://localhost:8000"
if fn_name == "get_latest_speeches":
resp = requests.get(f"{base_url}/speeches/latest", params=args)
elif fn_name == "search_speeches":
resp = requests.get(f"{base_url}/speeches/search", params=args)
return resp.json()
# Chat with function calling
chat = model.start_chat()
response = chat.send_message("What are the latest Fed speeches about inflation?")
# Process function calls in response
for part in response.parts:
if hasattr(part, 'function_call'):
fn = part.function_call
result = handle_function_call(fn.name, dict(fn.args))
# Send result back to model
response = chat.send_message(str(result))
```
---
## HTTP API Reference
When using the HTTP API wrapper, these endpoints are available:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/speeches/latest` | GET | Get latest speeches |
| `/speeches/search` | GET | Search by keyword |
| `/speeches/{doc_id}` | GET | Get specific speech |
| `/speeches/by-speaker` | GET | Filter by speaker |
| `/speeches/by-type` | GET | Filter by doc type |
| `/speeches/refresh` | POST | Fetch new speeches |
| `/speeches/stats` | GET | Get statistics |
### Query Parameters
- `limit` - Max results (default: 10, max: 50)
- `since_date` - ISO 8601 date filter
- `start_date` / `end_date` - Date range
- `name` - Speaker name (partial match)
- `role` - "Chair", "Vice Chair", or "Governor"
- `doc_type` - "speech", "testimony", or "prepared_remarks"
- `query` - Search keywords
---
## Running the MCP Server Directly
For native MCP clients:
```bash
# Run the MCP server
uv run fed-speech-mcp
# Run the HTTP API server
uv run fed-speech-http
```
---
## Available Tools
### `get_latest_speeches`
Get the latest Federal Reserve speeches, sorted by publication date.
**Parameters:**
- `limit` (optional): Maximum number of speeches (default: 10, max: 50)
- `since_date` (optional): Only return speeches after this date (ISO 8601)
### `get_speeches_by_speaker`
Filter speeches by speaker name and/or role.
**Parameters:**
- `name` (optional): Speaker name (partial match, e.g., "Powell")
- `role` (optional): "Chair", "Vice Chair", or "Governor"
- `start_date` (optional): Start date filter
- `end_date` (optional): End date filter
### `get_speeches_by_type`
Get speeches by document type.
**Parameters:**
- `doc_type` (required): "speech", "testimony", or "prepared_remarks"
- `start_date` (optional): Start date filter
- `end_date` (optional): End date filter
### `get_speech`
Get full content and metadata for a specific speech.
**Parameters:**
- `doc_id` (required): The unique document identifier
### `refresh_speeches`
Fetch new speeches from the Federal Reserve website.
**Parameters:**
- `include_index` (optional): Also scan index pages (slower but thorough)
- `years` (optional): Years to scan for index pages
### `search_speeches`
Search speeches by keyword.
**Parameters:**
- `query` (required): Search query
- `limit` (optional): Maximum results (default: 10)
### `get_speech_stats`
Get statistics about stored speeches.
## Output Format
Each speech document contains:
```json
{
"doc_id": "fed-speech-abc123def456",
"source": {
"publisher": "Board of Governors of the Federal Reserve System",
"collection": "speeches",
"url": "https://www.federalreserve.gov/...",
"retrieved_at": "2024-01-15T10:30:00Z"
},
"published_at": "2024-01-15T00:00:00Z",
"title": "Speech Title",
"speaker": {
"name": "Jerome H. Powell",
"role": "Chair",
"organization": "Board of Governors of the Federal Reserve System"
},
"doc_type": "speech",
"event": {
"name": "Economic Club of New York",
"location": "New York, NY"
},
"text": {
"raw": "...",
"clean": "..."
},
"features": {
"word_count": 2500,
"language": "en",
"has_qa": false,
"topics": {
"inflation": true,
"labor_market": true,
"rates": true,
"balance_sheet": false,
"growth": true,
"financial_stability": false
}
},
"importance": {
"tier": "high",
"score": 0.85,
"reasons": [
"Speaker is Chair (Jerome H. Powell)",
"Discusses rates in context of inflation"
]
}
}
```
## Importance Scoring
The importance score is calculated using these rules:
| Factor | Adjustment |
|--------|------------|
| Chair or Vice Chair speaker | Base: High |
| Governor speaker | Base: Medium |
| Testimony | +1 tier |
| Contains Q&A | +1 tier |
| Discusses rates + (inflation or labor market) | +1 tier |
| Word count < 300 | -1 tier |
## Topic Detection
Topics are detected by keyword matching:
- **Inflation**: inflation, prices, CPI, PCE, price stability
- **Labor Market**: employment, unemployment, wages, jobs
- **Rates**: interest rate, fed funds, hike, cut, monetary policy
- **Balance Sheet**: QE, QT, runoff, asset purchases
- **Growth**: GDP, demand, recession, economic activity
- **Financial Stability**: banking, liquidity, stress, systemic risk
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `FED_SPEECH_DATA_DIR` | Data storage directory | `./data` |
| `FED_SPEECH_HTTP_TIMEOUT` | HTTP request timeout (seconds) | `30` |
| `FED_SPEECH_MAX_RETRIES` | Max retry attempts | `3` |
| `FED_SPEECH_HTTP_PORT` | HTTP API server port | `8000` |
## Data Storage
```
data/
├── speeches/ # Processed JSON documents
│ ├── fed-speech-xxx.json
│ └── ...
└── raw/ # Raw HTML content (for traceability)
├── 20240115_abc123.html
└── ...
```
## Development
### Running Unit Tests
```bash
# Install with dev dependencies
uv sync --dev
# Run all tests
uv run pytest
# Run with verbose output
uv run pytest -v
# Run specific test file
uv run pytest tests/test_models.py
# Run with coverage
uv run pytest --cov=fed_speech_mcp
```
### Running Local Integration Tests
```bash
# Test all MCP functionality end-to-end
uv run python scripts/test_local.py all
# Test specific functionality
uv run python scripts/test_local.py refresh --limit 3
uv run python scripts/test_local.py search --query "rates"
```
### Project Structure
```
fed-speech-mcp/
├── src/fed_speech_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── http_server.py # HTTP API wrapper
│ ├── config.py # Configuration
│ ├── models/ # Pydantic data models
│ ├── ingestion/ # RSS/index discovery & fetching
│ ├── parsing/ # HTML parsing & normalization
│ ├── features/ # Feature extraction & scoring
│ └── storage/ # JSON storage layer
├── data/ # Data directory
├── pyproject.toml
└── README.md
```
## License
MIT
## Acknowledgments
Data sourced from the [Federal Reserve Board](https://www.federalreserve.gov/).
