📊 finwatch-mcp

A custom MCP Server for financial portfolio monitoring, risk analysis, and compliance — powered by LangGraph + Claude.

Turn natural language into actionable financial intelligence. Ask your portfolio questions like "What's my risk exposure to tech stocks?" or "Flag any anomalous movements in the last 24h" and get data-driven answers in seconds.

![Python 3.11+](https://python.org) ![MCP Protocol](https://modelcontextprotocol.io) ![LangGraph](https://github.com/langchain-ai/langgraph) ![License: MIT](LICENSE)

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                   CLIENT LAYER                          │
│   Claude Desktop  │  Gradio UI  │  CLI  │  Telegram     │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Protocol (JSON-RPC)
┌────────────────────────▼────────────────────────────────┐
│              LANGGRAPH AGENT (Orchestrator)              │
│  Multi-step reasoning · Report generation · Triage      │
│  Claude API · StateGraph · Human-in-the-loop            │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Tool Calls
┌────────────────────────▼────────────────────────────────┐
│              FINWATCH MCP SERVER                        │
│                                                         │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────────┐  │
│  │ get_portfolio │ │ analyze_risk │ │ detect_anomaly │  │
│  └──────────────┘ └──────────────┘ └────────────────┘  │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────────┐  │
│  │search_filings│ │get_market_kpi│ │compliance_check│  │
│  └──────────────┘ └──────────────┘ └────────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                    DATA LAYER                            │
│  SQLite (prices, KPIs)  │  ChromaDB (SEC filings, RAG)  │
│  Alpha Vantage · Finnhub · FRED · SEC EDGAR             │
└─────────────────────────────────────────────────────────┘

Features

MCP Server Tools

| Tool | Description | |------|-------------| | get_portfolio | Real-time portfolio status: holdings, P&L, sector allocation | | analyze_risk | Risk metrics: VaR, Sharpe ratio, Beta, max drawdown | | detect_anomaly | Flag unusual price movements, volume spikes, correlation breaks | | search_filings | RAG-powered semantic search over SEC filings and earnings reports | | get_market_kpi | Macro indicators: interest rates, inflation, sector performance | | compliance_check | Validate portfolio against exposure limits and concentration rules |

LangGraph Agent

Multi-step reasoning: chains tool calls to answer complex questions
Report generation: automated daily/weekly portfolio summaries
Anomaly triage: investigates detected anomalies with root cause analysis
Human-in-the-loop: asks for confirmation before high-impact actions

Quick Start

Prerequisites

Python 3.11+
uv (recommended) or pip
API keys: Alpha Vantage (free), Finnhub (free), Anthropic (for agent)

Installation

# Clone the repo
git clone https://github.com/geraldo96/finwatch-mcp.git
cd finwatch-mcp

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e ".[dev]"

# Copy environment template
cp .env.example .env
# Edit .env with your API keys

Run the MCP Server

# Start the MCP server (Streamable HTTP)
uv run python -m src.mcp_server.server

# The server runs on http://localhost:8080/mcp

Connect to Claude Desktop

Add to your claude_desktop_config.json: ``json { "mcpServers": { "finwatch": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``

Run the LangGraph Agent (standalone)

# Interactive CLI mode
uv run python -m src.agent.cli

# Example queries:
# > What's my current portfolio allocation?
# > Is my tech exposure within compliance limits?
# > Show me anomalies from the last week and explain them

Run with Docker

docker compose up
# MCP server: http://localhost:8080/mcp
# Gradio UI:  http://localhost:7860

Data Sources

| Source | Data | API Key | Rate Limit (free) | |--------|------|---------|-------------------| | Alpha Vantage | Stock prices, fundamentals | Free | 25 req/day | | Finnhub | Real-time quotes, news, sentiment | Free | 60 req/min | | FRED | Macro indicators, interest rates | Free | 120 req/min | | SEC EDGAR | 10-K, 10-Q filings | None | 10 req/sec | | Yahoo Finance | Historical prices (backup) | None | Unofficial |

Project Structure

finwatch-mcp/
├── src/
│   ├── mcp_server/
│   │   ├── server.py          # MCP server entrypoint (Streamable HTTP)
│   │   ├── tools/
│   │   │   ├── portfolio.py   # get_portfolio tool
│   │   │   ├── risk.py        # analyze_risk tool
│   │   │   ├── anomaly.py     # detect_anomaly tool
│   │   │   ├── filings.py     # search_filings tool (RAG)
│   │   │   ├── market_kpi.py  # get_market_kpi tool
│   │   │   └── compliance.py  # compliance_check tool
│   │   └── config.py          # Server configuration
│   ├── agent/
│   │   ├── graph.py           # LangGraph StateGraph definition
│   │   ├── nodes.py           # Agent nodes (reason, act, report)
│   │   ├── state.py           # Agent state schema
│   │   └── cli.py             # Interactive CLI client
│   ├── data/
│   │   ├── ingester.py        # Data fetching & sync logic
│   │   ├── models.py          # SQLAlchemy / Pydantic models
│   │   └── db.py              # Database connection & queries
│   └── rag/
│       ├── embeddings.py      # BAAI embedding pipeline
│       ├── indexer.py         # SEC filing indexer
│       └── retriever.py       # ChromaDB retrieval
├── tests/
│   ├── test_tools.py          # Unit tests for MCP tools
│   ├── test_agent.py          # Agent integration tests
│   └── test_data.py           # Data layer tests
├── scripts/
│   ├── seed_data.py           # Seed DB with sample portfolio
│   ├── ingest_filings.py      # Download & index SEC filings
│   └── demo.py                # Full demo walkthrough
├── docs/
│   ├── ARCHITECTURE.md        # Detailed architecture docs
│   └── TOOLS.md               # MCP tool specifications
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
├── .env.example
└── README.md

Development Roadmap

Week 1 — Foundation

[x] Project scaffold & CI setup
[ ] MCP server with get_portfolio and analyze_risk tools
[ ] SQLite data layer + Alpha Vantage / yfinance ingestion
[ ] Sample portfolio seeding script

Week 2 — RAG & Anomaly Detection

[ ] ChromaDB setup + SEC EDGAR filing indexer
[ ] search_filings tool with BAAI embeddings
[ ] detect_anomaly tool (z-score + rolling stats)
[ ] get_market_kpi tool (FRED integration)

Week 3 — Agent & Orchestration

[ ] LangGraph StateGraph with Claude API
[ ] Multi-step reasoning chains
[ ] compliance_check tool
[ ] Interactive CLI client

Week 4 — Polish & Deploy

[ ] Docker Compose (server + agent + Gradio UI)
[ ] Comprehensive tests
[ ] Demo video / GIF
[ ] Hugging Face Space (optional)

Tech Stack

| Layer | Technology | |-------|-----------| | MCP Server | Python mcp SDK, Streamable HTTP | | Agent | LangGraph, Claude API (Anthropic SDK) | | Structured Data | SQLite + SQLAlchemy | | Vector Store | ChromaDB + BAAI/bge-small-en-v1.5 | | Data Sources | Alpha Vantage, Finnhub, FRED, SEC EDGAR, yfinance | | UI | Gradio (demo), Claude Desktop (production) | | Deploy | Docker Compose | | Testing | pytest, pytest-asyncio |

Contributing

Contributions are welcome! Please read the contributing guidelines first.

License

MIT License — see LICENSE for details.

---

Built by Geraldo Margjini as a portfolio project demonstrating MCP Server development, LangGraph agent orchestration, and financial data engineering.

finwatch-mcp