Metadata-Version: 2.4
Name: capital-advantage-mcp
Version: 0.1.2
Summary: MCP server for Capital Advantage — Indian financial analytics for Claude and other AI assistants
Project-URL: Homepage, https://beta.capitaladvantage.finance
Project-URL: Documentation, https://beta.capitaladvantage.finance
Author: Capital Advantage
License: Proprietary
License-File: LICENSE
Keywords: bse,finance,india,mcp,nifty,nse,stocks
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: httpx>=0.26.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Capital Advantage MCP Server

Institutional-grade Indian financial analytics for Claude and other AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io/).

Screen 3,400+ stocks, analyze 40,000+ mutual funds, run quant models (GARCH, HMM, copula), price bonds, track FII/DII flows, and more — all from natural language in Claude.

## Features

### Market Data (4 tools)
| Tool | Description |
|------|-------------|
| `search_stocks` | Search 3,400+ Indian stocks by name or symbol |
| `get_stock_quote` | Real-time price, volume, 52-week range, PE, market cap |
| `get_market_snapshot` | Full market overview — indices, FII/DII, movers, news in one call |
| `get_fii_dii_activity` | Foreign & domestic institutional buy/sell/net flows with chart |

### Stock Analysis (5 tools)
| Tool | Description |
|------|-------------|
| `get_stock_fundamentals` | PE, PB, ROE, ROCE, margins, growth rates, returns |
| `get_stock_financials` | Income statement, balance sheet, cash flow (5 years) |
| `get_stock_analysis` | RSI, MACD, Bollinger Bands, beta, alpha, drawdown analysis |
| `get_peer_comparison` | Compare against sector peers on 87+ metrics with percentile ranks |
| `get_shareholding_pattern` | Quarterly FII/DII/Promoter/Public breakdown with 8-quarter trend chart |

### Stock Screening (2 tools)
| Tool | Description |
|------|-------------|
| `screen_stocks` | Filter 3,400+ stocks by PE, ROE, market cap, sector, returns, and more |
| `get_screener_presets` | Pre-built screens: value picks, growth stocks, dividend yield, momentum |

### Quant Lab (8 tools)
| Tool | Description |
|------|-------------|
| `get_regime_detection` | Hidden Markov Model — detect BULL/BEAR/NEUTRAL regimes with transition probabilities |
| `get_garch_forecast` | GARCH/EGARCH/GJR-GARCH volatility forecast with confidence intervals |
| `get_volatility_cone` | Volatility cone — rolling windows vs historical percentile bands |
| `get_jump_detection` | Merton jump-diffusion model fitting + Lee-Mykland jump detection |
| `get_tail_risk` | VaR, CVaR (Expected Shortfall), EVT/GPD tail risk with backtesting |
| `get_copula_analysis` | Fit 5 copula families to stock pairs, analyze tail dependence |
| `get_dcc_correlation` | DCC-GARCH dynamic correlation between 2-5 stocks |
| `get_distribution_analysis` | Fit 6 probability distributions, identify best fit by AIC |

### Derivatives (2 tools)
| Tool | Description |
|------|-------------|
| `get_options_chain` | Full options chain with strikes, expiries, Greeks, IV, OI, max pain |
| `calculate_option_greeks` | Black-Scholes Greeks calculator (delta, gamma, theta, vega, rho) |

### Mutual Funds (5 tools)
| Tool | Description |
|------|-------------|
| `search_mutual_funds` | Search 40,000+ Indian mutual funds by name |
| `get_mf_details` | Fund details, NAV history (5 years), 1M to 5Y returns |
| `analyze_mutual_fund` | Sharpe, Sortino, max drawdown, Calmar, win rate analysis |
| `screen_mutual_funds` | Filter by category, AMC, AUM, expense ratio, returns |
| `compare_mutual_funds` | Side-by-side comparison of multiple funds |

### Fixed Income (5 tools)
| Tool | Description |
|------|-------------|
| `calculate_bond` | Bond price, YTM, duration, convexity — all in one call |
| `get_rbi_rates` | RBI policy rates, T-Bill yields, G-Sec benchmarks, money market rates |
| `get_gsec_yields` | India 10Y G-Sec historical yields + India-US spread |
| `search_isin` | Search ~50,000 Indian ISINs (bonds, G-Secs, CPs, CDs) |
| `compare_fixed_deposits` | FD returns comparison with post-tax calculations |

### Forex, Crypto & Commodities (4 tools)
| Tool | Description |
|------|-------------|
| `get_forex_rates` | 22 currency rates vs INR with buy/sell and day change |
| `get_crypto_prices` | BTC, ETH, SOL and 5 more cryptos in INR with history |
| `get_commodity_prices` | Gold, silver, crude oil, natural gas, copper, platinum + MCX futures |
| `calculate_gold_silver` | Gold/silver price calculator by weight and purity (24K/22K/18K) |

### News & Heatmap (3 tools)
| Tool | Description |
|------|-------------|
| `get_market_news` | Market news by category or sector (business, economy, IT, Banking, etc.) |
| `get_company_news` | Company-specific news articles |
| `get_sector_heatmap` | Sector performance heatmap — which sectors are up/down today |

**Total: 38 tools** covering stocks, mutual funds, fixed income, derivatives, quant models, forex, crypto, commodities, and news.

## Installation

```bash
pip install capital-advantage-mcp
```

Or run directly with `uvx` (no install needed):
```bash
uvx capital-advantage-mcp
```

## Configuration

Get your API key at [beta.capitaladvantage.finance/settings/developer](https://beta.capitaladvantage.finance/settings/developer).

### Claude Desktop (macOS)

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

```json
{
  "mcpServers": {
    "capital-advantage": {
      "command": "capital-advantage-mcp",
      "env": {
        "CA_API_KEY": "ca_your_key_here"
      }
    }
  }
}
```

### Claude Desktop (Windows)

Add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "capital-advantage": {
      "command": "capital-advantage-mcp",
      "env": {
        "CA_API_KEY": "ca_your_key_here"
      }
    }
  }
}
```

### Using uvx (no install)

```json
{
  "mcpServers": {
    "capital-advantage": {
      "command": "uvx",
      "args": ["capital-advantage-mcp"],
      "env": {
        "CA_API_KEY": "ca_your_key_here"
      }
    }
  }
}
```

## Usage Examples

### 1. Stock Screening
**Prompt:** "Find undervalued Nifty 50 stocks with PE below 15 and ROE above 15%"

Claude will use `screen_stocks` with filters `{index: "NIFTY 50", pe_max: 15, roe_min: 15}` and return matching stocks ranked by market cap.

### 2. Quant Analysis
**Prompt:** "Is Reliance Industries in a bull or bear phase? Run regime detection."

Claude will call `get_regime_detection` with `{symbol: "RELIANCE"}` and return the current HMM-detected regime (BULL/BEAR/NEUTRAL), transition probabilities, confidence level, and a timeline chart showing regime changes overlaid on price history.

### 3. Mutual Fund Comparison
**Prompt:** "Compare SBI Bluechip Fund vs Axis Bluechip Fund over the last 3 years"

Claude will first use `search_mutual_funds` to find scheme codes, then call `compare_mutual_funds` to get side-by-side Sharpe ratio, Sortino, max drawdown, volatility, and returns for both funds.

### 4. Bond Pricing
**Prompt:** "Calculate the YTM and duration for a 7.26% coupon bond maturing in 10 years, trading at 102"

Claude will call `calculate_bond` with `{coupon_rate: 7.26, market_price: 1020, years_to_maturity: 10, ytm_input: 7.0}` and return calculated price, YTM, current yield, and premium/discount analysis.

### 5. Market Overview
**Prompt:** "Give me a complete market snapshot — indices, FII activity, top movers, and which sectors are up today"

Claude will call `get_market_snapshot` for indices + FII/DII + movers, and `get_sector_heatmap` for sector performance breakdown.

## Pricing

- **Free**: 100 API calls/day
- **Pro**: Higher limits for power users

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CA_API_KEY` | Yes | Your Capital Advantage API key |
| `CA_BACKEND_URL` | No | Custom backend URL (defaults to production) |

## Privacy & Data Policy

**What data does this MCP server collect?**

- **API Key**: Your API key is sent to the Capital Advantage backend over HTTPS with every request. The backend stores a SHA-256 hash of the key for authentication — the raw key is never stored.
- **Request logs**: The backend logs API call counts and timestamps for rate limiting. IP addresses may be logged for abuse prevention.
- **No personal data**: The MCP server itself is stateless — it does not store any user data, conversation history, or query results locally.
- **No data selling**: Capital Advantage does not sell, share, or monetize user data or API usage patterns with any third parties.
- **HTTPS only**: All communication between the MCP server and backend uses TLS encryption.

For questions about data handling, contact: support@capitaladvantage.finance

## Troubleshooting

### "CA_API_KEY environment variable is required"
You need to set your API key in the Claude Desktop config. Get one at [beta.capitaladvantage.finance/settings/developer](https://beta.capitaladvantage.finance/settings/developer).

### "401 Unauthorized" or "Invalid API key"
Your API key may be invalid or expired. Generate a new one from the developer settings page.

### "429 Too Many Requests"
You've exceeded your rate limit (100 calls/day on free tier). Wait for the daily reset or upgrade to Pro.

### "Connection timeout" or "Network error"
The Capital Advantage backend may be temporarily unavailable. Try again in a few minutes.

### Tool returns empty or unexpected data
Some tools require market hours for live data (Indian markets: 9:15 AM - 3:30 PM IST, Monday-Friday). Historical data and analysis tools work anytime.

## Support

- **Email**: support@capitaladvantage.finance

## License

Proprietary — Copyright (c) 2026 Capital Advantage. All rights reserved.
