# groww-mcp

An unofficial Model Context Protocol (MCP) server and client for the Groww Trade API. Claude Desktop, Claude Code, MCP Inspector, agent frameworks or the bundled CLI can use it to read your portfolio and market data, and to place orders through a safety pipeline.

> **Disclaimer.** This is an independent open-source project. It is not affiliated with, endorsed by or supported by Groww. "Groww" is used only to say which API this software talks to.
>
> Trading involves risk of loss. This software is provided **as is, without warranty** (see [LICENSE](LICENSE)). It is not investment advice. You are responsible for every order placed with it, for keeping your credentials safe, and for following Groww's API terms and SEBI rules that apply to you. Test with `GROWW_MCP_DRY_RUN=true` (the default) before trading real money.

**Safety default:** `GROWW_MCP_DRY_RUN=true`. No order reaches Groww until you set `GROWW_MCP_DRY_RUN=false`. Even then, every order needs a passing preview and a single-use 60-second confirmation token for that exact order, and clients that support it show an on-screen confirmation too.

## Packages

One repository, three separately installable distributions:

| Package | Distribution | What it is | Depends on |
|---|---|---|---|
| [`packages/contracts`](packages/contracts/README.md) | `groww-mcp-contracts` | The wire contract: pydantic result models shared by server and client | pydantic |
| [`packages/server`](packages/server/README.md) | `groww-mcp` | The MCP server (`groww-mcp` command) | contracts, `growwapi`, `mcp` |
| [`packages/client`](packages/client/README.md) | `groww-mcp-client` | Async client library and the `groww-mcp-cli` command | contracts, `mcp`, `rich` |
| [`packages/mcpb`](packages/mcpb/README.md) | `groww-mcp-<version>.mcpb` | The server packaged as a Claude Desktop extension, with a settings screen | built from server + contracts |

The client never imports the server or the Groww SDK; it speaks MCP only. The test suite enforces this, and it also checks that every typed client helper matches the output schema the server publishes.

```
packages/contracts/   groww_mcp_contracts  (models.py, types.py)
packages/server/      groww_mcp            (server, tools, resources, prompts, order pipeline, live feed)
                      scripts/             live smoke tests, SDK introspection, fixture tools
                      tests/               unit, protocol, safety, transport, integration, live
packages/client/      groww_mcp_client     (client.py library, cli.py)
packages/mcpb/        Claude Desktop extension: manifest.json, entry point, build.py
examples/             runnable examples; the test suite executes them
docs/                 configuration guide, SDK surface notes, verification log
```

## Install (Windows, PowerShell)

**Claude Desktop users:** install the extension ([packages/mcpb](packages/mcpb/README.md)). Nothing else is needed.

**Command-line tools** for Claude Code, the CLI and other local apps (needs [uv](https://docs.astral.sh/uv/)):

```powershell
uv tool install .\packages\server        # puts groww-mcp on PATH
uv tool install .\packages\client        # puts groww-mcp-cli on PATH
groww-mcp init                            # asks for credentials and settings, writes ~/.groww-mcp/.env
```

**Development** (editable installs, tests):

```powershell
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -e packages/contracts -e "packages/client[dev]" -e "packages/server[dev]"
```

The server alone (no client, no dev tools) is `pip install -e packages/contracts -e packages/server`. The client alone is `pip install -e packages/contracts -e packages/client`.

## Configure

There are three ways, all ending in the same settings:

| You use | How you configure |
|---|---|
| The Claude Desktop extension | Its settings screen (Settings → Extensions → Groww → Configure) |
| `groww-mcp` from the command line | `groww-mcp init`, which writes the env file for you |
| Either | Edit the env file by hand |

The server reads one env file: `--env-file`, else `GROWW_MCP_ENV_FILE`, else `~/.groww-mcp/.env`.

- **Credentials** come from that file or the extension's settings screen. The server never asks for them over MCP. The minimum is:

  ```
  GROWW_TOTP_API_KEY=...
  GROWW_TOTP_SEED=...
  ```

- **Trading settings** (DRY_RUN, segments, limits) can be in the file too. Any that are missing are asked for through Claude or the CLI the first time they're needed, and saved to the file.

**[docs/configuration.md](docs/configuration.md)** walks through generating the TOTP credentials on Groww, where the file lives, how values are loaded, and troubleshooting. Every setting is listed in [`packages/server/.env.example`](packages/server/.env.example).

## Connect

### Claude Desktop

**Recommended:** install the extension. See [packages/mcpb/README.md](packages/mcpb/README.md).

**By hand** (development): add this to `%APPDATA%\Claude\claude_desktop_config.json` (the same file is in [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)). Use absolute paths, because Claude Desktop starts servers from its own working directory:

```json
{
  "mcpServers": {
    "groww": {
      "command": "C:\\path\\to\\groww-mcp\\.venv\\Scripts\\groww-mcp.exe",
      "args": ["--env-file", "C:\\Users\\<you>\\.groww-mcp\\.env"]
    }
  }
}
```

Then quit Claude Desktop from the system tray and reopen it.

### Claude Code

```powershell
claude mcp add groww -- groww-mcp --env-file C:\Users\<you>\.groww-mcp\.env
```

### MCP Inspector

```powershell
npx @modelcontextprotocol/inspector groww-mcp --env-file C:\Users\<you>\.groww-mcp\.env
```

### Command line

```powershell
.venv\Scripts\groww-mcp-cli --env-file ..\.env
```

See the [client README](packages/client/README.md) for every command, and [`examples/`](examples/README.md) for library usage.

## Development

```powershell
.venv\Scripts\python -m pytest -n auto        # all packages, no network, about 1-3 minutes
.venv\Scripts\python -m ruff check .
.venv\Scripts\python -m mypy
```

Live tests hit your real Groww account and are opt-in; see the [server README](packages/server/README.md#tests).

## Status

| Phase | Status |
|---|---|
| 1. Discovery ([`docs/sdk_surface.md`](docs/sdk_surface.md), [`MIGRATION_NOTES.md`](MIGRATION_NOTES.md)) | done |
| 2. Foundation: config, TOTP session, SDK wrapper | done |
| 3. Read-only tools, resources, prompts | done |
| 4. Order pipeline and write tools | done |
| 5. Smart orders (GTT/OCO), live feed, resource subscriptions | done |
| 6. Client library and CLI (the Flask bridge was dropped: the legacy Flask app was removed on 2026-10-16) | done |
| 7. Gated live write tests during market hours, final docs | pending |

Verification results for each phase are in [`docs/verification.md`](docs/verification.md).

## Contributing and security

- [CONTRIBUTING.md](CONTRIBUTING.md): setting up, running the checks, and submitting changes.
- [SECURITY.md](SECURITY.md): report vulnerabilities privately, not in public issues.
- [CHANGELOG.md](CHANGELOG.md): what changed in each version.

## License

[MIT](LICENSE) © 2026 Rithesh Madhava