MCP Financial Data Gateway
Retrieves the CNN Fear & Greed Index, a market sentiment indicator that measures investor emotions based on seven factors.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCP Financial Data Gateway
10 financial data tools. 1 universal MCP layer. Any LLM can use it in 60 seconds.
Why This Exists
The biggest bottleneck in enterprise AI adoption isn't model quality — it's data connectivity. Every team building an AI agent today faces the same problem: wiring up data sources one at a time, with brittle custom integrations that break when APIs change. MCP (Model Context Protocol) is Anthropic's answer — a single standard for connecting any data source to any LLM, the same way USB-C standardized device charging. This project demonstrates what that looks like in practice: ten financial data tools across six APIs — market data, economic indicators, sentiment, insider activity, and event calendars — unified behind a single discoverable interface that any MCP-compatible agent can call without writing a line of integration code.
Related MCP server: Wealthnow
Architecture
graph LR
subgraph Clients["MCP Clients · stdio"]
CD[Claude Desktop]
CA[Custom Agent]
CR[Cursor IDE]
end
TS[MCP Server<br/>server.py]
subgraph Tools["10 Tool Handlers"]
TG1["Market Data<br/>stock · crypto · forex"]
TG2["Economic Intel<br/>indicators · yields · fear&greed"]
TG3["Market Intel<br/>news · insider trades"]
TG4["Calendars<br/>economic · IPO"]
end
subgraph MW["Middleware Pipeline"]
CACHE[Cache<br/>TTLCache · 5-min]
RL[Rate Limiter<br/>per-provider quotas]
NORM[Validator<br/>Pydantic v2]
ERR[Error Handler<br/>safe_execute]
end
subgraph APIs["External APIs · Free Tier"]
AV[Alpha Vantage<br/>25 req/day]
FRED[FRED<br/>120 req/min]
FX[ExchangeRate API<br/>open endpoint]
CG[CoinGecko<br/>30 req/min]
FH[Finnhub<br/>60 req/min]
SEC[SEC EDGAR<br/>10 req/sec]
FG[CNN Fear & Greed<br/>public]
end
Clients -->|stdio| TS
TS --> Tools
Tools -->|"① check"| CACHE
CACHE -->|"② miss"| RL
RL -->|"③ fetch"| APIs
APIs -->|"④ raw"| NORM
NORM -->|"⑤ write"| CACHE
RL -.->|rate exceeded| ERR
NORM -.->|on error| ERR
style TS fill:#4A90D9,stroke:#2E6BA6,color:#fff
style CACHE fill:#F5A623,stroke:#D4891A,color:#fff
style NORM fill:#7B68EE,stroke:#5B48CE,color:#fff
style RL fill:#E74C3C,stroke:#C0392B,color:#fff
style ERR fill:#2ECC71,stroke:#27AE60,color:#fffEvery tool call follows the same middleware chain: cache check → rate limit → API call → Pydantic validation → cache write. Errors at any stage return a structured ErrorResponse — the server never crashes.
The 10 Tools
Market Data
Tool | Source | Example Query |
| Alpha Vantage | "What's NVIDIA's current price?" → |
| CoinGecko · no key | "Bitcoin's market cap?" → |
| ExchangeRate-API · no key | "USD to JPY rate?" → |
Economic Intelligence
Tool | Source | Example Query |
| FRED | "Show me CPI trend" → |
| FRED | "Is the yield curve inverted?" → no params |
| CNN · no key | "How fearful is the market?" → no params |
Market Intelligence
Tool | Source | Example Query |
| SEC EDGAR · no key | "Are AAPL insiders buying?" → |
| Finnhub | "Any merger news?" → |
Calendars
Tool | Source | Example Query |
| FRED | "What data drops this week?" → defaults to next 7 days |
| Finnhub | "Any IPOs this month?" → defaults to next 30 days |
Four tools require no API key at all (Forex, Crypto, Insider Trades, Fear & Greed) — run them immediately after cloning.
Quick Start
Step 1 — Clone
git clone https://github.com/ranjittilekar/financial-data-gateway-mcp.git
cd financial-data-gateway-mcpStep 2 — Install
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .Step 3 — Configure
cp .env.example .env
# Edit .env with your three API keys (Alpha Vantage, FRED, Finnhub — all free, ~60 sec each)
# Also set SEC_EDGAR_USER_AGENT="AppName Your Name email@example.com" (SEC policy, no key needed)
# ExchangeRate-API, CoinGecko, and SEC EDGAR need no API keyStep 4 — Run
# Option A: MCP server (for Claude Desktop / any MCP client)
python run_server.py
# Option B: Standalone demo UI
streamlit run demo/streamlit_app.pyUsage with Claude Desktop
Add this to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"financial-data-gateway": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["run_server.py"],
"cwd": "/absolute/path/to/ai-pm-01-mcp-financial-gateway",
"env": {
"ALPHA_VANTAGE_API_KEY": "your_key",
"FRED_API_KEY": "your_key",
"FINNHUB_API_KEY": "your_key",
"SEC_EDGAR_USER_AGENT": "FinancialDataGateway Your Name email@example.com"
}
}
}
}Important: Use the absolute path to your virtualenv's Python, not bare
python. Claude Desktop doesn't inherit your shell's PATH.
Example conversation after connecting:
You: Should I invest in NVIDIA? Show me the stock price, recent insider activity, the treasury yield curve, the Fear & Greed Index, and any major economic events this week.
Claude: (calls
get_stock_quote("NVDA"),get_insider_trades("NVDA"),get_treasury_yields(),get_fear_greed_index(),get_economic_calendar(...)simultaneously)NVIDIA (NVDA): Trading at $875.40, up +2.1% today. Insiders have been net sellers — 3 Sale transactions totaling $12.4M in the past 30 days, with no open-market purchases. The yield curve is normal (+0.49% spread), suggesting no near-term recession signal. However, the Fear & Greed Index sits at 19 (Extreme Fear) — market-wide sentiment has deteriorated sharply over the past month from 45 to 19. Upcoming this week: PCE inflation data (Friday, high impact) and jobless claims (Thursday)...
Usage as Standalone (Streamlit Demo)
streamlit run demo/streamlit_app.py
The demo includes 11 tabs:
Stocks — real-time quote with OHLCV metrics
Economic Data — FRED time series with line chart
Forex — live FX rates with inverse calculation
Crypto — price + market cap + 24h change
News — latest market headlines by category
Insider Trades — SEC Form 4 filings as a formatted table
Treasury Yields — full yield curve + inversion badge (green/red)
Fear & Greed — color-coded score with all 7 component indicators
Economic Calendar — upcoming US data releases grouped by impact
IPO Calendar — upcoming listings with price range and exchange
Multi-Query — ask a question in plain English; Gemini picks all 10 tools, fetches data, and synthesizes a full answer
Technical Decisions
Component | Choice | Why |
Transport | stdio (local) | Simplest MCP transport; zero infrastructure to demo. SSE is the upgrade path for multi-client deployments. |
Caching |
| Financial data doesn't need sub-second freshness. 5 minutes cuts API calls dramatically in demo sessions while staying meaningful. |
Validation | Pydantic v2 models | Validates API responses at the boundary, auto-generates JSON schemas for MCP tool registration — two problems solved by one dependency. |
Rate limiting | Sliding window, per-provider | Alpha Vantage has both a per-minute (5/min) and daily (25/day) quota. Both are tracked atomically before each call so the daily budget is never silently burned. |
Error handling | Centralized |
|
HTTP client |
| Non-blocking; the MCP server runs in an asyncio event loop and httpx fits naturally. Treasury yields fetch 8 series concurrently via |
Dependency injection | Middleware instances passed as kwargs | One |
Evals
259 tests, 6 test files, 0 mocks of business logic.
evals/test_middleware.py 50 tests Unit tests — CacheManager, RateLimiter,
ResponseNormalizer, ErrorHandler
evals/test_tools.py 93 tests All 10 tool handlers — cache mutation,
from_cache flag, schema roundtrip,
missing key, live API fixtures
evals/test_stock_quotes.py }
evals/test_economic_data.py } 45 tests Per-tool integration tests with
evals/test_forex_rates.py } live API calls (session-scoped fixtures,
evals/test_crypto_prices.py } one call shared per test session)
evals/test_market_news.py }
evals/test_integration.py 22 tests End-to-end MCP server tests — list_tools,
call_tool, error shape, description qualityRun the suite:
pytest evals/ -v --tb=short
# → ~255 passed, ~4 skipped in ~10s
# Skips are live Alpha Vantage tests when the free daily quota is exhausted —
# handled gracefully with pytest.skip(), not errors.Invariants enforced by tests:
Every successful response contains a
_metablock withsource,retrieved_at,from_cacheA second identical call always returns
from_cache: trueCache hits never mutate the stored object (copy-on-return pattern)
ErrorHandler.safe_execute()never propagates an exception — tested against 6 failure modesAll 10 tool descriptions are ≥ 80 characters with example values (LLM routing quality check)
Alpha Vantage daily cap fires correctly after minute windows reset (monkeypatched clock test)
Fear & Greed index returns exactly 7 component indicators
Treasury yields return exactly 8 maturities with float rates
Lessons Learned
Trade-offs I Made
5-minute cache TTL — I chose 5 minutes as a balance between API quota conservation and data freshness. Stock prices change by the second, but in the context of a demo or a planning conversation, a 5-minute-old quote is nearly always good enough. A production system would make TTL a per-tool configuration: 30 seconds for live prices, 1 hour for FRED economic data, 24 hours for news.
Free tier limits — All five APIs used are free, which creates real constraints: Alpha Vantage's 25 req/day limit means a heavy demo session can exhaust the daily budget in minutes. I handled this by building in both proactive rate limiting (tracks remaining quota before each call) and graceful degradation (returns structured error with retry guidance rather than crashing). The architectural lesson: design around your quota budget as a first-class constraint, not an afterthought.
stdio transport instead of SSE — stdio is the simplest MCP transport and works perfectly for a single local client. SSE (Server-Sent Events) would enable multiple concurrent clients and remote deployments. I chose stdio deliberately to ship faster and demonstrate the core value proposition; the upgrade path is documented.
What I'd Change With More Time
WebSocket streaming for live price tickers — push updates instead of poll-on-demand
SSE transport to support multi-client deployments and remote MCP servers
Historical data endpoints — FRED observations go back decades; surfacing time-range queries would make the economic data tool far more powerful for trend analysis
Tool composition — a
get_market_summarymeta-tool that calls all 5 in parallel and returns a unified snapshot, useful for "give me a full briefing" queriesPersistent cache (Redis or SQLite) so the TTL budget survives server restarts in long-running deployments
Guardrails I Added
Sliding window rate limiter with per-provider quotas (not just a token bucket) — catches both per-minute bursts and daily budget exhaustion
Pydantic validation on every API response — if Alpha Vantage changes a field name, the error surfaces immediately with a clear message instead of silently passing bad data downstream
Copy-on-return for cache hits —
{**cached, "_meta": {**cached["_meta"], "from_cache": True}}creates a new dict rather than mutating the stored object; discovered this class of bug in testingsafe_execute()wrapper —ErrorHandlercatchesRateLimitError,httpx.HTTPError,ValidationError,ValueError, and bareException; the MCP server returns a valid JSON response in every caseAlpha Vantage soft-error detection — the API returns 200 OK with
{"Note": "..."}for per-minute limits and{"Information": "..."}for daily limits; both are detected by key presence and raised asRateLimitErrorbefore Pydantic ever sees the response
Project Structure
ai-pm-01-mcp-financial-gateway/
├── run_server.py # Entry point: python run_server.py
├── src/
│ ├── server.py # MCP orchestrator — registers all 10 tools, wires middleware
│ ├── tools/ # 10 tool handlers (dependency-injected pattern)
│ ├── middleware/ # CacheManager, RateLimiter, ResponseNormalizer, ErrorHandler
│ └── models/schemas.py # Pydantic v2 models for all 10 tools + ErrorResponse
├── demo/streamlit_app.py # Standalone demo UI — 11 tabs + Gemini multi-query
├── evals/ # 259 tests across 6 files
├── docs/
│ ├── SETUP.md # Step-by-step setup for Claude Desktop
│ └── lessons-learned.md # Extended PM reflections
└── claude_desktop_config.json # Example MCP client configLicense
MIT — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
Your agent needs markets — prices and fundamentals for listed companies, the filings behind them, crypto, and what the prediction markets put the odds at. **What you can ask for** • "Pull this company's income statement, cash flow and balance sheet for the last 8 quarters." • "What did insiders buy or sell, and when?" • "Snapshot prices for these 50 tickers, then the OHLC history for the three that moved." • "What are the current odds on this event across Kalshi and Polymarket?" • "Screen for companies matching these financial criteria." **How to use it** Point any MCP client at https://mcp.aisa.one/finance/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: prices and snapshots, income statements, balance sheets and cash flows, metrics and ratios, earnings and analyst estimates, filings and line-item search, insider trades, macro interest rates, news, a screener; CoinGecko spot prices, market tables, OHLC, per-venue tickers and trending; Kalshi and Polymarket markets and trades; plus EDINET filings for Japan. **Why this rather than the source** Equities, crypto and event markets behind one account, so a cross-asset question is one conversation. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Read the number here, then ask the same agent what X is saying about the ticker today — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/marketpulse/mcp · /crypto-market-data/mcp · /prediction-market-data/mcp · /stock-pulse/mcp for one slice each.
75 MCP tools: SEC financials, FRED economics, IRS 990, FDA, FX, UK Companies House.
Your agent needs company financials it can compute on — statements, ratios, earnings, estimates, filings and insider activity as structured data, not a PDF. **What you can ask for** • "Give me 8 quarters of income statement, balance sheet and cash flow for this ticker." • "What do analysts estimate for next quarter, and how did the last four surprise?" • "Find this exact line item across every filing." • "Who bought or sold as an insider in the last 90 days?" • "Screen for profitable companies under this valuation with growing revenue." **How to use it** Point any MCP client at https://mcp.aisa.one/marketpulse/mcp and sign in with OAuth — there is no key to create or paste. 21 tools: prices and snapshots, income statements, balance sheets, cash-flow statements, financial metrics and snapshots, earnings, analyst estimates, company facts, filings and filing items, line-item search, a screener, insider trades, macro interest rates, news, plus EDINET documents and filing digests for Japanese issuers. **Why this rather than the source** Statements as fields you can compute on, and a screener in the same place. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Read the fundamentals here, then ask the same agent what social is saying about the ticker — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/finance/mcp for equities, crypto and prediction markets in one place.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides live financial data for any LLM agent, including stock quotes, crypto prices, SEC filings, XBRL financials, FX rates, and macro indicators, through ten MCP tools.11115 npm1MIT
- AlicenseNot gradedqualityBmaintenanceInstitutional financial data for AI agents: credit, private markets, options history, filings.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to retrieve US stock market OHLCV data, company fundamentals and financial statements, FRED macroeconomic indicators, market news, Reddit/StockTwits sentiment, and Polymarket prediction market probabilities via simple tools.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and backend workflows to access standardized multi-market financial data, technical indicators, fundamentals, news, filings, money flow, and CSV/JSON exports through MCP tools and HTTP endpoints.-