fmp-mcp 0.1.0__tar.gz

fmp_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+venv/
+__pycache__/
+*.pyc
+.DS_Store
+.env
+cache/
+dist/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/

fmp_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Henry Chien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fmp_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: fmp-mcp
+Version: 0.1.0
+Summary: MCP server for Financial Modeling Prep - 19 tools for market data via Claude
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: zstandard
+Provides-Extra: estimates
+Requires-Dist: psycopg2-binary; extra == 'estimates'
+Description-Content-Type: text/markdown
+
+# fmp-mcp
+
+Financial intelligence for your AI agent — powered by live market data.
+
+Give Claude (or any MCP-compatible AI) the ability to analyze stocks, screen markets, compare peers, read earnings calls, and track sector rotations — all grounded in real financial data from [Financial Modeling Prep](https://financialmodelingprep.com/).
+
+This isn't a raw API wrapper. Each tool is purpose-built for a specific analytical task, composing multiple data sources into structured, analysis-ready outputs designed for AI consumption.
+
+## What your AI can do
+
+**Market Intelligence**
+- `get_market_context` — One-call market snapshot: indices, sectors, gainers/losers, economic events
+- `get_sector_overview` — Sector and industry performance with P/E valuations
+- `get_news` — Stock-specific or broad market news
+- `get_events_calendar` — Earnings, dividends, splits, and IPO calendars
+- `get_economic_data` — Economic indicators and high-impact event tracking
+
+**Fundamental Analysis**
+- `fmp_fetch` — Direct access to 60+ financial data endpoints (income statements, balance sheets, cash flows, key metrics, and more)
+- `compare_peers` — Side-by-side peer comparison across 12 financial ratios
+- `get_earnings_transcript` — Parsed earnings calls with speaker attribution and Q&A sections
+
+**Stock Screening & Discovery**
+- `screen_stocks` — Screen by sector, market cap, beta, dividend, volume, and more
+- `get_institutional_ownership` — Institutional holder analytics and ownership trends
+- `get_insider_trades` — Insider transaction flow and statistics
+- `get_etf_holdings` — ETF/fund holdings, sector and country allocation
+
+**Technical Analysis**
+- `get_technical_analysis` — Composite signals from 7 indicators (SMA, EMA, RSI, MACD, Bollinger, ADX, Williams %R) with buy/sell scoring
+
+**Analyst Sentiment**
+- `get_estimate_revisions` — Historical EPS/revenue estimate revision trends
+- `screen_estimate_revisions` — Screen for estimate momentum across a universe of stocks
+
+**Data Discovery**
+- `fmp_list_endpoints` — Browse all 60+ available data endpoints by category
+- `fmp_describe` — Get parameter documentation for any endpoint
+- `fmp_search` — Search for companies by name or ticker
+- `fmp_profile` — Company profile with sector, industry, and key stats
+
+## Install
+
+```bash
+pip install fmp-mcp
+```
+
+Optional estimate-revision tools (requires PostgreSQL):
+
+```bash
+pip install "fmp-mcp[estimates]"
+```
+
+## Configuration
+
+Set your API key:
+
+```bash
+export FMP_API_KEY="your_key"
+```
+
+Optional settings:
+
+- `FMP_CACHE_DIR` — Custom cache directory (default: `~/.cache/fmp-mcp/`)
+- `FMP_CACHE_MAXSIZE` — Max in-memory cache entries (default: 200)
+
+## Run
+
+```bash
+fmp-mcp
+```
+
+Or use with Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "fmp-mcp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["fmp-mcp"],
+      "env": { "FMP_API_KEY": "your_key" }
+    }
+  }
+}
+```
+
+## How it's different
+
+| | Raw API wrapper | fmp-mcp |
+|---|---|---|
+| **Approach** | Expose every endpoint 1:1 | Purpose-built analytical tools |
+| **Output** | Raw JSON, dozens of fields | Structured, summarized, analysis-ready |
+| **Composition** | One API call per tool | Multiple sources stitched together |
+| **AI-optimized** | Generic descriptions | Tool descriptions and schemas designed for LLM tool selection |
+| **Caching** | None | Per-endpoint disk caching with configurable refresh strategies |
+
+## Requirements
+
+- Python 3.11+
+- FMP API key ([get one here](https://financialmodelingprep.com/developer/docs/))

fmp_mcp-0.1.0/README.md

@@ -0,0 +1,101 @@
+# fmp-mcp
+
+Financial intelligence for your AI agent — powered by live market data.
+
+Give Claude (or any MCP-compatible AI) the ability to analyze stocks, screen markets, compare peers, read earnings calls, and track sector rotations — all grounded in real financial data from [Financial Modeling Prep](https://financialmodelingprep.com/).
+
+This isn't a raw API wrapper. Each tool is purpose-built for a specific analytical task, composing multiple data sources into structured, analysis-ready outputs designed for AI consumption.
+
+## What your AI can do
+
+**Market Intelligence**
+- `get_market_context` — One-call market snapshot: indices, sectors, gainers/losers, economic events
+- `get_sector_overview` — Sector and industry performance with P/E valuations
+- `get_news` — Stock-specific or broad market news
+- `get_events_calendar` — Earnings, dividends, splits, and IPO calendars
+- `get_economic_data` — Economic indicators and high-impact event tracking
+
+**Fundamental Analysis**
+- `fmp_fetch` — Direct access to 60+ financial data endpoints (income statements, balance sheets, cash flows, key metrics, and more)
+- `compare_peers` — Side-by-side peer comparison across 12 financial ratios
+- `get_earnings_transcript` — Parsed earnings calls with speaker attribution and Q&A sections
+
+**Stock Screening & Discovery**
+- `screen_stocks` — Screen by sector, market cap, beta, dividend, volume, and more
+- `get_institutional_ownership` — Institutional holder analytics and ownership trends
+- `get_insider_trades` — Insider transaction flow and statistics
+- `get_etf_holdings` — ETF/fund holdings, sector and country allocation
+
+**Technical Analysis**
+- `get_technical_analysis` — Composite signals from 7 indicators (SMA, EMA, RSI, MACD, Bollinger, ADX, Williams %R) with buy/sell scoring
+
+**Analyst Sentiment**
+- `get_estimate_revisions` — Historical EPS/revenue estimate revision trends
+- `screen_estimate_revisions` — Screen for estimate momentum across a universe of stocks
+
+**Data Discovery**
+- `fmp_list_endpoints` — Browse all 60+ available data endpoints by category
+- `fmp_describe` — Get parameter documentation for any endpoint
+- `fmp_search` — Search for companies by name or ticker
+- `fmp_profile` — Company profile with sector, industry, and key stats
+
+## Install
+
+```bash
+pip install fmp-mcp
+```
+
+Optional estimate-revision tools (requires PostgreSQL):
+
+```bash
+pip install "fmp-mcp[estimates]"
+```
+
+## Configuration
+
+Set your API key:
+
+```bash
+export FMP_API_KEY="your_key"
+```
+
+Optional settings:
+
+- `FMP_CACHE_DIR` — Custom cache directory (default: `~/.cache/fmp-mcp/`)
+- `FMP_CACHE_MAXSIZE` — Max in-memory cache entries (default: 200)
+
+## Run
+
+```bash
+fmp-mcp
+```
+
+Or use with Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "fmp-mcp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["fmp-mcp"],
+      "env": { "FMP_API_KEY": "your_key" }
+    }
+  }
+}
+```
+
+## How it's different
+
+| | Raw API wrapper | fmp-mcp |
+|---|---|---|
+| **Approach** | Expose every endpoint 1:1 | Purpose-built analytical tools |
+| **Output** | Raw JSON, dozens of fields | Structured, summarized, analysis-ready |
+| **Composition** | One API call per tool | Multiple sources stitched together |
+| **AI-optimized** | Generic descriptions | Tool descriptions and schemas designed for LLM tool selection |
+| **Caching** | None | Per-endpoint disk caching with configurable refresh strategies |
+
+## Requirements
+
+- Python 3.11+
+- FMP API key ([get one here](https://financialmodelingprep.com/developer/docs/))

fmp_mcp-0.1.0/fmp/AGENT_PROMPTING_GUIDE.md

@@ -0,0 +1,223 @@
+# FMP Agent Prompting Quick Reference
+
+Use this guide when tasking Claude agents to perform financial analysis using the FMP package.
+
+> **Full API Reference:** See `fmp/API_REFERENCE.json` for complete endpoint schemas and response columns.
+
+## Basic Usage
+
+```python
+from fmp import FMPClient
+from fmp.exceptions import FMPEmptyResponseError
+
+fmp = FMPClient()
+
+# All endpoints use fmp.fetch() - returns a pandas DataFrame
+df = fmp.fetch("income_statement", symbol="AAPL", period="annual", limit=3)
+
+# Check for empty results
+if not df.empty:
+    for _, row in df.iterrows():
+        print(row['revenue'])
+
+# Handle endpoints that may return no data (e.g., dividends for non-payers)
+try:
+    dividends = fmp.fetch("dividends", symbol="GOOG")
+except FMPEmptyResponseError:
+    print("No dividend history")
+```
+
+## Prompt Template
+
+```
+Use the FMP package at `fmp/` to [task].
+
+```python
+from fmp import FMPClient
+from fmp.exceptions import FMPEmptyResponseError
+fmp = FMPClient()
+```
+
+Use `fmp.fetch("[endpoint]", symbol="[SYMBOL]", ...)` to fetch [what].
+
+Analyze:
+1. [Question 1]
+2. [Question 2]
+
+Write and execute a Python script.
+```
+
+## Endpoint Quick Reference
+
+| Endpoint | Use For | Key Params |
+|----------|---------|------------|
+| `historical_price_adjusted` | Stock returns, drawdowns | `symbol`, `from`, `to` |
+| `historical_price_eod` | Raw OHLCV prices | `symbol`, `from`, `to` |
+| `treasury_rates` | Yield curve, rates | `from`, `to` |
+| `income_statement` | Revenue, earnings, margins | `symbol`, `period`, `limit` |
+| `balance_sheet` | Assets, debt, equity | `symbol`, `period`, `limit` |
+| `cash_flow` | FCF, capex, dividends paid | `symbol`, `period`, `limit` |
+| `key_metrics` | ROE, P/E, ratios | `symbol`, `period`, `limit` |
+| `dividends` | Dividend history | `symbol` |
+| `analyst_estimates` | EPS/revenue forecasts | `symbol`, `period`, `limit` |
+| `price_target` | Analyst price targets | `symbol` |
+| `earnings_transcript` | Earnings call transcript text | `symbol`, `year`, `quarter` |
+| `sec_filings` | SEC filing metadata with links | `symbol`, `type`, `limit` |
+| `search` | Find companies | `query`, `limit` |
+| `profile` | Company info | `symbol` |
+
+## Ready-to-Use Prompts
+
+### Stock Performance Comparison
+```
+Use the FMP package at `fmp/` to compare stock performance.
+
+```python
+from fmp import FMPClient
+fmp = FMPClient()
+# Example: fmp.fetch("historical_price_adjusted", symbol="AAPL", **{"from": "2024-01-01", "to": "2024-12-31"})
+```
+
+Use `historical_price_adjusted` to fetch prices for [TICKER1], [TICKER2], [TICKER3]
+from [START_DATE] to [END_DATE].
+
+Calculate: total return, max drawdown, and rank by performance.
+
+Write and execute a Python script.
+```
+
+### Company Financial Health
+```
+Use the FMP package at `fmp/` to analyze [COMPANY] financial health.
+
+```python
+from fmp import FMPClient
+fmp = FMPClient()
+# Example: fmp.fetch("income_statement", symbol="AAPL", period="annual", limit=3)
+```
+
+Fetch `income_statement`, `balance_sheet`, and `key_metrics` for [TICKER] (last 3 years).
+Use `profile` first to confirm you have the correct company.
+
+Summarize: revenue trend, profitability (margins, ROE), and balance sheet strength.
+
+Write and execute a Python script.
+```
+
+### Dividend Analysis
+```
+Use the FMP package at `fmp/` to compare dividends.
+
+```python
+from fmp import FMPClient
+from fmp.exceptions import FMPEmptyResponseError
+fmp = FMPClient()
+# Note: dividends endpoint raises FMPEmptyResponseError for non-dividend payers
+```
+
+Use `dividends` endpoint for [TICKER1], [TICKER2], [TICKER3].
+Handle FMPEmptyResponseError for companies that don't pay dividends.
+
+Analyze: payment frequency, recent amounts, dividend growth, and current yield.
+
+Write and execute a Python script.
+```
+
+### Analyst Expectations
+```
+Use the FMP package at `fmp/` to analyze analyst expectations for [TICKER].
+
+```python
+from fmp import FMPClient
+fmp = FMPClient()
+```
+
+Fetch `analyst_estimates` (annual, limit=5) and `price_target`.
+
+Summarize: EPS trajectory, revenue growth expectations, and price target consensus.
+
+Write and execute a Python script.
+```
+
+### Sector/Industry Comparison
+```
+Use the FMP package at `fmp/` to compare companies in [SECTOR].
+
+```python
+from fmp import FMPClient
+fmp = FMPClient()
+```
+
+For [TICKER1], [TICKER2], [TICKER3], fetch `key_metrics` and `income_statement`.
+
+Compare: margins, ROE, growth rates, and valuation multiples.
+
+Write and execute a Python script.
+```
+
+### Treasury Yield Analysis
+```
+Use the FMP package at `fmp/` to analyze Treasury yields.
+
+```python
+from fmp import FMPClient
+fmp = FMPClient()
+```
+
+Use `treasury_rates` from [START_DATE] to [END_DATE].
+
+Columns: month1, month3, month6, year1, year2, year5, year10, year30.
+
+Analyze: yield curve shape, inversions, rate changes over period.
+
+Write and execute a Python script.
+```
+
+## Common Column Names
+
+**profile:** `companyName`, `sector`, `industry`, `currency`, `description`
+
+**income_statement:** `date`, `calendarYear`, `revenue`, `netIncome`, `eps`, `grossProfit`, `operatingIncome`
+
+**balance_sheet:** `date`, `totalAssets`, `totalStockholdersEquity`, `totalDebt`, `cashAndCashEquivalents`
+
+**cash_flow:** `date`, `operatingCashFlow`, `freeCashFlow`, `capitalExpenditure`, `stockBasedCompensation`, `dividendsPaid`
+
+**key_metrics:** `date`, `marketCap`, `enterpriseValue`, `peRatio`, `roe`, `roic`, `debtToEquity`, `evToSales`, `dividendYield`
+
+**historical_price_adjusted:** `date`, `adjClose`, `volume`
+
+**treasury_rates:** `date`, `month3`, `year2`, `year10`, `year30`
+
+**dividends:** `date`, `adjDividend`
+
+**analyst_estimates:** `date`, `revenueAvg`, `revenueLow`, `revenueHigh`, `epsAvg`, `epsLow`, `epsHigh`, `numAnalystsRevenue`, `numAnalystsEps`
+
+**price_target:** `lastMonthCount`, `lastMonthAvgPriceTarget`, `lastQuarterCount`, `lastQuarterAvgPriceTarget`, `lastYearCount`, `lastYearAvgPriceTarget`
+
+**price_target_consensus:** `targetHigh`, `targetLow`, `targetConsensus`, `targetMedian`
+
+**earnings_transcript:** `symbol`, `quarter`, `year`, `date`, `content` (full transcript text)
+
+**sec_filings:** `symbol`, `fillingDate`, `acceptedDate`, `cik`, `type`, `link`, `finalLink` (link to SEC.gov filing)
+
+## Tips
+
+1. **For sub-agents:** Start prompts with "First, read `fmp/AGENT_PROMPTING_GUIDE.md` and `fmp/API_REFERENCE.json`" — this gives the agent full context on available endpoints and usage patterns
+2. Always use `fmp.fetch("endpoint_name", symbol="TICKER", ...)` syntax
+2. Import `FMPEmptyResponseError` for endpoints that may return no data
+3. All responses are **pandas DataFrames** — use `df.empty`, `df.iterrows()`, `df.iloc[0]`
+4. Use `profile` first to confirm ticker maps to expected company
+5. Specify exact endpoint names from the table
+6. List symbols explicitly
+7. Mention expected columns to reduce errors
+8. Ask comparative questions ("which is best?")
+9. Request tables/summaries for clean output
+
+## Important Notes
+
+- **Return type:** All `fmp.fetch()` calls return pandas DataFrames, not dicts or lists
+- **Date params:** Use `**{"from": "2024-01-01", "to": "2024-12-31"}` for date range params (since `from` is a Python keyword)
+- **Empty responses:** Some endpoints (like `dividends`) raise `FMPEmptyResponseError` when no data exists
+- **Sorting:** DataFrames often come in reverse chronological order; use `df.sort_values('date')` if needed
+- **SEC filing content:** The `sec_filings` endpoint returns links to SEC.gov. To fetch content, use `requests` with a User-Agent header: `headers = {'User-Agent': 'Name (email)'}`