Mutual-Funds-Groww-MCP

<div align="center"> <img src="https://github.com/user-attachments/assets/73dc9208-c96f-47ec-851f-3ca2381aaab4" width="64" height="64" alt="logo" /> <h1>Mutual Funds Custom MCP Server</h1> </div>

An intelligent, professional-grade Model Context Protocol (MCP) server that connects Claude (and other MCP-enabled AI assistants) directly to Groww's live API.

When you ask your AI assistant for mutual fund recommendations or analysis (e.g., "Show me the best Flexi Cap funds with high returns and moderate risk"), the AI intelligently selects and applies multi-dimensional filters, queries Groww's backend in real time, and performs deep portfolio analysis to pick the best mutual funds for your needs.

---

🤖 How the AI Uses This MCP Server

Rather than manually browsing financial portals, your AI assistant autonomously handles fund discovery and analysis for you:

1. Intelligent Query Interpretation: You talk to Claude in plain natural language (e.g., "Find top-rated equity mutual funds managed by Quant or PPFAS sorted by 3-year returns").
2. Autonomous Filter Application: Claude automatically translates your request into exact filter criteria defined in [filters.py](file:///d:/Projects/GROWW%20MCP/filters.py) and invokes the search_mutual_funds tool.
3. Live Groww API Execution: The MCP server connects directly to Groww's live production endpoints (groww.in/v1/api), fetching real-time data.
4. Deep-Dive Fund Diagnostics: To pick and analyze the best funds, Claude invokes fetch_mutual_fund_details to examine the fund's top 10 holding companies, fund managers' experience & education, Sharpe/Sortino/Alpha/Beta risk metrics, CAGR vs category average, NAV, AUM, Expense Ratio, and Exit Load.

---

📽️ Demo Video

https://github.com/user-attachments/assets/9c28dd77-0fd1-4947-a0bf-f7c50a4e5248

📸 Screenshots

Real-Time Search & Deep-Dive Analysis

Claude executing real-time screener queries and analyzing detailed metrics, portfolio holdings, risk parameters, and CAGR. <img width="875" height="1027" alt="screenzy-1786277257050" src="https://github.com/user-attachments/assets/93e35df2-711f-43ce-8b57-3a5dcab9798f" />

---

🔥 Key Capabilities

• Direct Live Groww API Data: Always returns real-time, production-grade financial data directly from Groww—no stale datasets or mock data.
• Top 10 Portfolio Company Holdings: Extracts the exact top companies invested in by the fund, along with sector allocation and corpus percentage (corpus_percent).
• Fund Manager Profiling: Fetches fund managers' full names, educational background, and total career experience.
• Advanced Volatility & Risk Metrics: Evaluates Sharpe Ratio, Sortino Ratio, Alpha, Beta, and Standard Deviation alongside scheme risk levels (Low to Very High).
• CAGR & Benchmark Comparison: Compares 1Y, 3Y, 5Y, and since-launch CAGR against the benchmark index and category average, plus 1Y/2Y/3Y SIP return calculations.
• Clean LLM Optimization: Raw API JSON responses are automatically pruned to remove UI clutter, saving token context while preserving essential analytical data.

---

⚙️ Filter Capabilities Available to AI

The AI dynamically applies these filter enums from [filters.py](file:///d:/Projects/GROWW%20MCP/filters.py) according to your prompt requirements:

• Groww Verdict (GrowwVerdict): TOP_BUY, BUY, HOLD, SELL
• Asset Categories (AssetCategory): Equity, Debt, Hybrid, Commodities
• Sub-Categories (SubCategory):
  • Equity: Flexi Cap, Large Cap, Mid Cap, Small Cap, Large & MidCap, Multi Cap, ELSS, Sectoral, Thematic, Value Oriented, International
  • Debt: Liquid, Corporate Bond, Banking and PSU, Credit Risk, Dynamic Bond, Gilt, Money Market, Overnight, Short Duration, Ultra Short Duration, etc.
  • Hybrid: Aggressive Hybrid, Arbitrage, Balanced Hybrid, Conservative Hybrid, Dynamic Asset Allocation, Equity Savings, Multi Asset Allocation
  • Commodities: Gold, Silver
• Risk Profile (RiskLevel): Low, Moderately Low, Moderate, Moderately High, High, Very High
• Sorting Options (SortOption): Popularity (3), Prime Verdict (10), 1Y Returns (4), 3Y Returns (0), 5Y Returns (5)
• AMC / Fund Houses (FundHouse): 50+ fund houses supported (e.g., Axis Mutual Fund, HDFC Mutual Fund, SBI Mutual Fund, Quant Mutual Fund, PPFAS Mutual Fund, Mirae Asset Mutual Fund, etc.)
• Index Only: Option to narrow results strictly to Index Funds.

---

🚀 Installation & Authentication

1. Clone the Repository

git clone https://github.com/codeterrayt/Mutual-Funds-Groww-MCP.git
cd Mutual-Funds-Groww-MCP

2. Configure Authentication in auth.py

Because live data is fetched directly from Groww's authenticated backend endpoints, you need to fill in your session credentials in [auth.py](file:///d:/Projects/GROWW%20MCP/auth.py).

1. Log into your account on groww.in.
2. Open Developer Tools in your browser (F12 or Ctrl + Shift + I) and switch to the Network tab.
3. Search for any fund or refresh the page.
4. Select any network request to groww.in/v1/api and check the Headers section:
   • Copy the authorization header value (e.g., Bearer eyJ...).
   • Copy the cookie header value.
5. Open [auth.py](file:///d:/Projects/GROWW%20MCP/auth.py) and fill in your credentials:

# auth.py
AUTHORIZATION_TOKEN = "Bearer eyJ....."
COOKIE = "dso.....;"

---

🔌 Registering with Claude Desktop

Register this MCP server in Claude Desktop's process configuration file so Claude can execute these tools.

Claude Desktop Configuration Location

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json Snippet

Option 1: Using uv (Recommended)

uv will automatically manage dependencies using pyproject.toml and run the server.

{
  "mcpServers": {
    "groww-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "d:/Projects/GROWW MCP",
        "run",
        "main.py"
      ]
    }
  }
}

Option 2: Using standard Python executable

If you prefer running using your python environment:

{
  "mcpServers": {
    "groww-mcp": {
      "command": "d:/Projects/GROWW MCP/.venv/Scripts/python.exe",
      "args": [
        "d:/Projects/GROWW MCP/main.py"
      ]
    }
  }
}

(Note: Replace d:/Projects/GROWW MCP with your local repository path, ensuring path slashes are written as /).

After editing the config, stop Claude From System Tray and restart Claude Desktop. You will see the tools active in Claude Desktop.

<img width="2182" height="1128" alt="screenzy-1786276796934" src="https://github.com/user-attachments/assets/34e07f47-d1af-4a02-b037-dd2c3971edac" />

---

🛠️ MCP Tools Overview

1. search_mutual_funds

Searches and screens live mutual fund schemes from Groww based on criteria provided by the AI.

• Parameters: groww_verdict, categories, sub_categories, index_only, fund_houses, risk_levels, sort_by, search_query, page, size.

2. fetch_mutual_fund_details

Retrieves in-depth holdings, risk metrics, returns CAGR, and fund manager profiles using the fund's search_id.

• Parameters: search_id (e.g., quant-small-cap-fund-direct-growth).

---

⚖️ Disclaimer

This project is an open-source tool for personal research and analysis. It is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Groww (groww.in).

📄 License

This project is open-source software licensed under the MIT License.