Metadata-Version: 2.4
Name: mcp-finance
Version: 0.2.0
Summary: An MCP server providing finance tools: a yfinance wrapper, computed analytics, and financial calculators.
Project-URL: Homepage, https://github.com/JoshCap20/finance-mcp
Project-URL: Repository, https://github.com/JoshCap20/finance-mcp
Project-URL: Issues, https://github.com/JoshCap20/finance-mcp/issues
Author: Josh Caponigro
Maintainer: Josh Caponigro
License-Expression: MIT
License-File: LICENSE
Keywords: fastmcp,finance,financial-analytics,market-data,mcp,model-context-protocol,stocks,yfinance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: fastmcp>=3.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.7
Requires-Dist: yfinance>=0.2.40
Description-Content-Type: text/markdown

# Finance MCP

An MCP server of finance tools: a `yfinance` market-data wrapper, computed analytics,
and deterministic financial calculators.

## Tools

**Market data (yfinance)**

- `get_quote` — current price snapshot for one or more tickers: price, change, day/52-week ranges, market cap (batched; cached briefly).
- `get_price_history` — OHLCV bars plus a computed summary for a ticker, by period and interval (long windows are truncated; the summary covers the full window).
- `get_financials` — income statement, balance sheet, or cash flow (annual or quarterly) as line items by period; values in the company's reporting currency, with an optional line-item filter.
- `get_company_profile` — sector, industry, market cap, P/E, beta, business summary, plus recent dividends and stock splits.
- `get_analyst_data` — sell-side analyst consensus: price targets, consensus recommendation, and the recent rating trend (analyst counts over the last four months).
- `search_symbols` — resolve a company or instrument name to ticker symbol(s), best match first, across all instrument types (equity, ETF, crypto, …).
- `get_news` — recent news headlines for a ticker, newest first: title, publisher, link, publish time, and a short summary (no news returns an empty list, not an error).

**Analytics**

- `get_key_metrics` — valuation/profitability/leverage ratios (P/E, EV/EBITDA, margins, ROE, debt/equity, FCF, EPS, …) as reported by Yahoo; units noted per field.
- `analyze_performance` — total & annualized return, annualized volatility, max drawdown, and 50/200-day SMAs computed from the daily price series.

**Time value & loans**

- `time_value_of_money` — solve any one of present/future value, payment, rate, or periods (compound interest, annuities, CAGR); supports begin-of-period (annuity-due).
- `loan_schedule` — monthly payment, total interest, and optional amortization schedule for a fixed-rate loan/mortgage (nominal APR compounded monthly).

**Cashflow valuation**

- `npv` — net present value of equally-spaced cashflows (cashflow[0] at t=0).
- `irr` — internal rate of return; returns all real roots and flags non-uniqueness.
- `mirr` — modified IRR; single-valued given finance and reinvestment rates.
- `xnpv` / `xirr` — NPV/IRR of cashflows on actual calendar dates (Actual/365).

**Rates & fixed income**

- `convert_rate` — nominal ↔ effective annual rate (discrete or continuous compounding).
- `bond_price` — price plus Macaulay/modified duration and convexity at a given yield (priced on a coupon date).
- `bond_ytm` — yield to maturity from a bond's market price.

The calculators are pure and deterministic; the market-data and analytics tools fetch
live data (briefly cached) and surface source errors clearly. All tools return typed,
structured results and report invalid inputs as clear errors.

## Prompts

MCP prompts — reusable analysis templates the client exposes for you to invoke (Claude Code shows
them as slash commands; other clients surface them their own way).

- `analyze_stock` (arguments: `ticker`, optional `horizon`, default `12mo`) — single-stock deep-dive: fundamentals, growth-adjusted peer valuation, performance, analyst view, and news catalysts → bull/bear cases and a fair-value range with a horizon-framed verdict, citing the data behind each claim.

## Run

```bash
uv run mcp-finance        # stdio MCP server
```

Add to an MCP client (e.g. Claude) as:

```json
{ "mcpServers": { "finance": { "command": "uvx", "args": ["mcp-finance"] } } }
```
