savvy-mcp 0.2.0

Python SDK for Savvy - financial data and visualization

savvy-mcp

Python SDK for Savvy - financial data and visualization.

Get economic indicators, stock prices, and create beautiful charts with just a few lines of code.

Installation

pip install savvy-mcp

Quick Start

import savvy

# Set your API key (or use SAVVY_API_KEY environment variable)
savvy.configure(api_key="sk_...")

# Fetch economic data (returns pandas DataFrame)
df = savvy.economic_data.fetch("UNRATE", start="2020-01-01")
print(df.head())
#         date  value
# 0 2020-01-01    3.6
# 1 2020-02-01    3.5
# 2 2020-03-01    4.4

# Fetch stock data
df = savvy.stock_data.fetch("AAPL", period="1y")

# Create a visualization
chart = savvy.visualize(df, "Stock price over time")
print(chart.url)  # https://savvy-mcp.com/c/abc123

Features

Economic Data

Access data from 20+ sources including FRED, World Bank, IMF, ECB, and more:

# US unemployment rate
df = savvy.economic_data.fetch("UNRATE")

# GDP growth with date range
df = savvy.economic_data.fetch("GDP", start="2010-01-01", end="2023-12-31")

# Search for data series
results = savvy.economic_data.search("inflation")
for r in results:
    print(f"{r['provider']}: {r['series_id']} - {r['name']}")

# Compare across countries
df = savvy.economic_data.compare("unemployment", ["US", "Germany", "Japan"])

Stock Data

Get stock prices from Yahoo Finance:

# Historical data
df = savvy.stock_data.fetch("AAPL", period="1y")
df = savvy.stock_data.fetch("MSFT", period="5y", interval="1wk")

# Current quote
quote = savvy.stock_data.quote("AAPL")
print(f"AAPL: ${quote['price']:.2f} ({quote['change_percent']:+.2f}%)")

Cryptocurrency Data

# Bitcoin price history
df = savvy.crypto_data.fetch("BTC-USD", period="1y")

# Ethereum quote
quote = savvy.crypto_data.quote("ETH")

Visualization

Create charts with natural language:

# Simple visualization
chart = savvy.visualize(df, "Line chart of stock price over time")

# With options
chart = savvy.visualize(
    df,
    "Show closing prices with a trendline",
    title="AAPL Stock Price",
    theme="executive",
)

# Access chart URLs
print(chart.url)     # Interactive HTML
print(chart.png)     # PNG image
print(chart.svg)     # SVG image
print(chart.python)  # Python code

Configuration

import savvy

# Option 1: Use configure()
savvy.configure(api_key="sk_...")

# Option 2: Environment variable (recommended for production)
# export SAVVY_API_KEY=sk_...

# Option 3: Custom API URL (for development)
savvy.configure(api_key="sk_...", api_url="https://custom.api.com")

# Read current config
print(savvy.api_key)  # Returns configured key

Error Handling

from savvy import SavvyError, AuthenticationError, DataNotFoundError

try:
    df = savvy.economic_data.fetch("INVALID_SERIES")
except DataNotFoundError as e:
    print(f"Series not found: {e.series_id}")
except AuthenticationError:
    print("Invalid API key")
except SavvyError as e:
    print(f"API error: {e}")

Data Sources

Provider	Data Types	Example
FRED	US economic indicators	UNRATE, GDP, CPIAUCSL
World Bank	Global development	NY.GDP.MKTP.CD
IMF	Forecasts	gdp_growth
ECB	Eurozone rates	EONIA, EURUSD
Yahoo Finance	Stocks, ETFs, crypto	AAPL, SPY, BTC-USD
Zillow	Housing data	ZHVI:San Francisco
And 15+ more...

Requirements

• Python 3.9+
• pandas
• httpx

Links

• Documentation
• API Reference
• Get an API Key

License

MIT