# MCP Server – Financial Analyzer

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants access to real-time stock prices, financial statements, SEC filings, and analytical tools.

Built with [FastMCP](https://github.com/jlowin/fastmcp), powered by [yfinance](https://github.com/ranaroussi/yfinance) and [edgartools](https://github.com/dgunning/edgartools).

---

## Tools

### Stock Prices
| Tool | Description |
|---|---|
| `get_stock_price` | Current price, volume, 52-week range, market cap |
| `get_price_history` | OHLCV history with configurable period and interval |
| `get_stock_info` | Company profile, sector, employees, ownership |

### Fundamentals
| Tool | Description |
|---|---|
| `get_income_statement` | Revenue, gross profit, EBITDA, net income, EPS |
| `get_balance_sheet` | Assets, liabilities, equity, debt |
| `get_cash_flow` | Operating, investing, financing, free cash flow |
| `get_earnings_history` | EPS estimates vs actuals and surprise % |

### SEC Filings
| Tool | Description |
|---|---|
| `search_sec_filings` | List 10-K, 10-Q, 8-K, and other filings |
| `get_filing_sections` | Retrieve full text of specific sections (business, risk_factors, mda) |
| `get_company_facts` | EDGAR CIK, registered tickers, TTM financials from XBRL |

### Analysis
| Tool | Description |
|---|---|
| `calculate_financial_ratios` | P/E, P/B, EV/EBITDA, ROE, ROA, margins, leverage ratios |
| `analyze_trends` | YoY growth trends for any financial line item |
| `compare_stocks` | Side-by-side comparison of multiple tickers on any metric |
| `dcf_estimate` | Simplified DCF intrinsic value with margin of safety |

## Resources

| URI | Description |
|---|---|
| `market://overview` | Major US indices (S&P 500, NASDAQ, Dow, VIX, 10Y Treasury) |
| `market://sectors` | Daily performance of 11 GICS sectors via SPDR ETFs |

---

## Quickstart (local / stdio)

```bash
# 1. Clone and install
git clone https://github.com/YOUR_USERNAME/MCP-Server-Financial-Analyzer.git
cd MCP-Server-Financial-Analyzer
pip install uv
uv sync

# 2. Configure environment
cp .env.example .env
# Edit .env — set EDGAR_IDENTITY to "Your Name your@email.com"

# 3. Run (stdio mode for local use)
uv run financial-analyzer
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "financial-analyzer": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/MCP-Server-Financial-Analyzer", "financial-analyzer"],
      "env": {
        "EDGAR_IDENTITY": "Your Name your@email.com"
      }
    }
  }
}
```

### VS Code (Copilot)

Add to `.vscode/mcp.json` or user settings:

```json
{
  "servers": {
    "financial-analyzer": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/MCP-Server-Financial-Analyzer", "financial-analyzer"],
      "env": {
        "EDGAR_IDENTITY": "Your Name your@email.com"
      }
    }
  }
}
```

---

## Deploy to Render

This repo includes a `render.yaml` for one-click deployment.

1. Push to GitHub
2. Go to [render.com](https://render.com) → **New → Blueprint** → connect your repo
3. Set `EDGAR_IDENTITY` to your real name and email in the Render dashboard
4. Deploy — your MCP endpoint will be at `https://<service-name>.onrender.com/mcp`

### Connect remote clients to the deployed server

```json
{
  "mcpServers": {
    "financial-analyzer": {
      "type": "http",
      "url": "https://<service-name>.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
      }
    }
  }
}
```

The `MCP_AUTH_TOKEN` is auto-generated by Render and visible in your service's environment variables.

---

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `EDGAR_IDENTITY` | Yes | — | `"Name email"` per SEC fair-use policy |
| `TRANSPORT` | No | `stdio` | `stdio` for local, `streamable-http` for cloud |
| `HOST` | No | `0.0.0.0` | Bind address (HTTP mode only) |
| `PORT` | No | `8000` | Port (HTTP mode only) |
| `MCP_AUTH_TOKEN` | No | — | Bearer token to protect the HTTP endpoint |

---

## Disclaimer

This server provides financial data for informational and educational purposes only. It is not financial advice. Always verify data from authoritative sources before making investment decisions.