# 🚀 DOS Growth MCP Server (Python)

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
[![FastMCP](https://img.shields.io/badge/MCP-FastMCP-orange.svg)](https://github.com/modelcontextprotocol/python-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![uv](https://img.shields.io/badge/uv-0.4+-purple.svg)](https://github.com/astral-sh/uv)

**Ask an AI assistant questions about your connected trading account in plain English with DOS Growth.**

**Live service:** [https://dos-growth-mcp.onrender.com](https://dos-growth-mcp.onrender.com)

DOS Growth connects a supported brokerage account to Claude or any other MCP-compatible AI client. Once configured, you can ask for your portfolio value, balances, holdings, market data, option chains, and more without switching tabs.

> **What is MCP?** Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and live data.

## ✨ What can DOS Growth do?

Once connected, your AI client gains access to **18 tools**:

| Category | Example request |
|---|---|
| 💼 **Account & Portfolio** | *"What's my available balance?"* / *"Show my holdings"* |
| 📈 **Order Management** | *"Place a limit order for 10 shares of INFY at ₹1,800"* |
| 🧠 **Smart Orders (GTT/OCO)** | *"Set a trigger order if RELIANCE crosses ₹2,500"* |
| 📊 **Market Data** | *"Get the LTP for TCS and WIPRO"* / *"Show OHLC data"* |
| ⚡ **Derivatives (FNO)** | *"Show the NIFTY option chain"* / *"What are the greeks?"* |

<details>
<summary>See all 18 DOS Growth tools</summary>

- `dos_growth_get_profile` — Brokerage account profile
- `dos_growth_get_balance` — Available margins and cash balance
- `dos_growth_get_holdings` — Equity holdings
- `dos_growth_get_positions` — Live positions (Cash or FNO)
- `dos_growth_place_order` — Market, Limit, SL, and SL-M orders
- `dos_growth_modify_order` — Edit a pending order
- `dos_growth_cancel_order` — Cancel an open order
- `dos_growth_create_smart_order` — GTT or OCO smart orders
- `dos_growth_cancel_smart_order` — Cancel a smart-order leg
- `dos_growth_get_smart_order_list` — View active smart orders
- `dos_growth_get_quote` — Price, volume, and market-depth data
- `dos_growth_get_ltp` — Last Traded Price for multiple symbols
- `dos_growth_get_ohlc` — Open, High, Low, and Close values
- `dos_growth_get_historical_candles` — Historical data for analysis
- `dos_growth_get_option_chain` — Option chains for indices and stocks
- `dos_growth_get_greeks` — Delta, Theta, Gamma, and Vega
- `dos_growth_get_expiries` — Available expiry dates
- `dos_growth_get_contracts` — Contracts for a selected expiry

</details>

## 🛠️ Setup guide

> **Time needed:** About 10 minutes. No prior coding experience is required.

### Step 1 — Get the code

Clone your DOS Growth repository:

```bash
git clone <your-dos-growth-repository-url> dos-growth
cd dos-growth
```

Alternatively, use the repository page's **Code → Download ZIP** option and extract the archive.

### Step 2 — Install `uv`

`uv` installs and runs this Python project. Follow the official [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/), then verify it:

```bash
uv --version
```

### Step 3 — Create your brokerage API keys

DOS Growth currently integrates with the Groww Trade API through its official Python SDK.

1. Open the [Trade API keys page](https://groww.in/trade-api/api-keys).
2. Sign in and create an API key and API secret.
3. Store both credentials securely.

> Treat these credentials like a password. Never share them or commit them to Git.

### Step 4 — Configure DOS Growth

Copy `.env.example` to a new file named `.env.local`, then enter your credentials:

```env
DOS_GROWTH_API_KEY=your_api_key_here
DOS_GROWTH_API_SECRET=your_api_secret_here
# Optional: DOS_GROWTH_API_TOKEN=your_predefined_token_if_available
```

For compatibility with earlier installations, `GROWW_API_KEY`, `GROWW_API_SECRET`, and `GROWW_API_TOKEN` are also accepted as fallback names.

### Step 5 — Install dependencies and start DOS Growth

```bash
uv sync
uv run main.py
```

The server runs at `http://127.0.0.1:8000`. Keep the terminal open while using an MCP client.

### Step 6 — Connect Claude Desktop

Open Claude Desktop, go to **Settings → Developer**, and select **Edit Config**. Add:

```json
{
  "mcpServers": {
    "dos_growth": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/sse"
      ]
    }
  }
}
```

Save the configuration and restart Claude Desktop. **DOS Growth** should appear as a connected MCP server.

### Step 7 — Try it

- *"What is my current account balance?"*
- *"Show me my holdings."*
- *"What's the LTP for RELIANCE and TCS?"*

## ☁️ Free cloud deployment on Render

The included `Dockerfile` and `render.yaml` deploy DOS Growth as a free Render web service with an HTTPS `onrender.com` subdomain.

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/Dikshu143644/dos-growth-mcp)

Configure these values as Render secrets during deployment:

- `DOS_GROWTH_ACCESS_TOKEN` — a long, random token that protects the MCP endpoints
- `DOS_GROWTH_API_KEY` and `DOS_GROWTH_API_SECRET` — your brokerage API credentials
- `DOS_GROWTH_API_TOKEN` — optional pre-generated brokerage token

The public health endpoint is `/health`, and the protected MCP endpoint is `/sse`.

Use the deployed service from Claude Desktop on Windows with this configuration, replacing the URL and token:

```json
{
  "mcpServers": {
    "dos_growth": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://dos-growth-mcp.onrender.com/sse",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer replace_with_your_access_token"
      }
    }
  }
}
```

> Never put the access token or brokerage credentials in Git. Render stores these values as encrypted environment secrets.

## 🔌 Other MCP clients

Any MCP-compatible client can connect while DOS Growth is running:

- **SSE endpoint:** `http://127.0.0.1:8000/sse`

## 🧪 Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector uv run main.py
```

This opens a browser interface where developers can call each tool and inspect its response.

## ❓ Troubleshooting

**DOS Growth does not appear as a connected tool**

Make sure the server is running, save the MCP client configuration, and restart the client.

**`uv: command not found`**

Restart the terminal after installing `uv`. If needed, review the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).

**`DOS_GROWTH_API_KEY` is missing or authentication fails**

Confirm `.env.local` is in the project root and that the variable names are spelled exactly as shown.

**Port 8000 is already in use**

Stop the other process using that port before starting DOS Growth.

## 📜 Project identity

- **App:** DOS Growth
- **Company:** DOS
- **Developer:** Dikshu
- **License:** MIT

Developed for the community by **Dikshu** at **DOS**.

---

*⚠️ Disclaimer: DOS Growth is an unofficial, community-built wrapper for the Groww Trade API. DOS Growth, DOS, and Dikshu are not affiliated with or endorsed by Groww. Trading involves financial risk. Use this software at your own discretion and always verify orders before placing them.*