Metadata-Version: 2.4
Name: mftool-mcp
Version: 0.3.0
Summary: MCP Server for publicly available Indian Mutual Funds data
Project-URL: Homepage, https://github.com/yourusername/mftool-mcp
Project-URL: Repository, https://github.com/yourusername/mftool-mcp
Project-URL: Issues, https://github.com/yourusername/mftool-mcp/issues
Author-email: SujitN <nayakwadi.sujit@rediffmail.com>
License: MIT
License-File: LICENSE
Keywords: amfi,claude,finance,india,llm,mcp,mftool,model-context-protocol,mutual-funds,nav,nse,share-market
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: mftool>=3.3
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.NayakwadiS/mftool-mcp -->
# 🇮🇳 mftool-mcp

> **MCP Server for publicly available Indian Mutual Funds data**  
> Powered by [mftool](https://github.com/NayakwadiS/mftool) · Works with Claude, Cursor, and any MCP-compatible LLM client

[![PyPI](https://img.shields.io/badge/pypi-v0.2.0-orange)](https://pypi.org/project/mftool-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

---

## What is this?

`mftool-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives any LLM client access to **Indian Mutual Fund data**.

Ask your AI assistant questions like:
- *"What is the current NAV of SBI Bluechip Direct Growth?"*
- *"Show me 3-year returns for HDFC Midcap Opportunities Fund"*
- *"List all schemes under Mirae Asset AMC"*
- *"Find all flexi cap funds and compare their 5-year returns"*

---

## Tools Available

| Tool | Description |
|---|---|
| `get_scheme_quote` | Live NAV for any scheme by AMFI scheme code |
| `get_bulk_quotes` | Live NAV for multiple schemes at once (concurrent) |
| `get_scheme_historical_nav` | Full NAV history for a scheme (all available dates) |
| `get_scheme_historical_nav_for_dates` | NAV history filtered to a specific date range (DD-MM-YYYY) |
| `get_scheme_history` | NAV history via BSE/YFinance code with period or date range |
| `get_scheme_codes` | All AMFI scheme codes and names |
| `get_available_schemes` | All schemes under a specific AMC |
| `get_scheme_details` | Fund house, type, category, start date (AMFI code) |
| `get_scheme_info` | Rich scheme info — AUM, returns, ratings (BSE/YFinance code) |
| `is_valid_scheme_code` | Validate an AMFI numeric scheme code |
| `is_valid_new_scheme_code` | Validate a BSE/new format scheme code |
| `search_schemes` | Search schemes by name keyword with relevance ranking |
| `search_schemes_by_amc` | Search schemes within a specific AMC |
| `search_schemes_by_type` | Search schemes by type/category (equity, debt, elss, etc.) |
| `get_average_aum` | Average AUM (domestic & overseas) for all AMCs by quarter |
| `get_equity_scheme_performance` | Daily performance for all equity funds (1Y/3Y/5Y returns) |
| `get_debt_scheme_performance` | Daily performance for all debt funds (1Y/3Y/5Y returns) |
| `get_hybrid_scheme_performance` | Daily performance for all hybrid funds (1Y/3Y/5Y returns) |
| `get_solution_scheme_performance` | Daily performance for solution-oriented funds (retirement, children) |
| `get_other_scheme_performance` | Daily performance for index funds and Fund of Funds |
| `calculate_returns` | Calculate SIP returns — absolute return % and annualised IRR |
| `get_cache_stats` | View hit/miss stats for NAV and scheme code caches |
| `clear_cache` | Clear all cached data to force fresh fetches |
| `set_cache_enabled` | Enable or disable mftool caching globally |

---

## Quick Start

### Using `uvx` (Recommended — no install needed)

```bash
uvx mftool-mcp
```

### Using `pip`

```bash
pip install mftool-mcp
mftool-mcp
```

---

## Claude Desktop Setup

Add this to your `claude_desktop_config.json`:

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

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

Restart Claude Desktop. You'll see **mftool-mcp** listed under connected tools.

---

## Cursor / Other MCP Clients

In your MCP client settings, add:

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

---

## Example Conversations

**Finding a fund:**
> You: "Find all SBI midcap mutual fund scheme codes"  
> Claude: *calls `search_schemes_by_amc(amc_name='sbi', query='midcap')`*  
> Claude: "Here are the SBI midcap schemes: SBI Magnum Midcap Fund - Direct Growth (code: 125497)..."

**Live NAV:**
> You: "What's the current NAV of scheme 125497?"  
> Claude: *calls `get_scheme_quote(scheme_code='125497')`*  
> Claude: "SBI Magnum Midcap Fund - Direct Growth: NAV ₹234.56 (as of 05-Apr-2025)"

**Performance comparison:**
> You: "Compare 5-year returns for large cap equity funds"  
> Claude: *calls `get_equity_scheme_performance()`*  
> Claude: "Here's the 5-year return comparison for Large Cap funds: ..."

---

## Data Source

All data is sourced via the `mftool` library. Data accuracy depends on published figures. This tool is for **informational purposes only** and does not constitute financial advice.

---

## Development

```bash
git clone https://github.com/NayakwadiS/mftool-mcp
cd mftool-mcp
pip install -e ".[dev]"

# Run the server locally
python -m mftool_mcp.server
```

<!-- ### Project Structure

```
mftool-mcp/
├── src/
│   └── mftool_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server entry point
│       └── tools/
│           ├── __init__.py
│           ├── nav.py         # NAV & historical data tools
│           ├── schemes.py     # Scheme discovery & search tools
│           └── performance.py # Daily performance tools
├── pyproject.toml
├── LICENSE
└── README.md
```
-->

---

## Acknowledgements

- [mftool](https://github.com/NayakwadiS/mftool) — the underlying data library

## Associated Initiatives

- NSE Stock predictions *[NSE-Neuron](https://github.com/NayakwadiS/NSE-Neuron)*
