nubra-mcp 0.1.1

Nubra MCP server for Codex and other MCP clients

Nubra MCP Server

A Python MCP server for Nubra built on FastMCP.

This repo is designed to let MCP clients such as Codex connect to Nubra for:

• authentication
• instrument lookup and ref-id resolution
• quotes and historical data
• option-chain and derivatives analysis
• holdings, funds, positions, and portfolio reporting
• TA/indicator scans via nubra-talib
• backtesting via vectorbt
• local report and CSV export workflows
• UAT-only trading actions with strict environment guardrails

What This MCP Supports

Read-only workflows

• auth state and session checks
• cash, futures, and options instrument discovery
• quotes, current price, and previous-close change
• historical OHLCV fetch and CSV export
• options analytics and chain summaries
• portfolio summary, holdings, positions, and funds
• HTML and image-based portfolio reports
• watchlist scanning and strategy helper tools
• trade journal summaries
• backtest reports and equity curve exports

Trading workflows

Trading is intentionally limited:

• order placement is allowed only in UAT
• order modification is allowed only in UAT
• order cancellation is allowed only in UAT
• square-off is allowed only in UAT
• options strategy execution is allowed only in UAT
• all trading actions are blocked in PROD

The guardrail exists in both the MCP tool layer and the service layer.

Safety Model

This repo is meant to be public-safe if used correctly.

What should be committed:

• source code
• .env.example
• .mcp.json
• docs
• tests

What should never be committed:

• .env
• auth_state.json
• personal phone numbers
• MPIN values
• OTPs
• generated reports and exports

Each user of this MCP should create their own local .env and log in with their own Nubra account.

Project Structure

• [server.py](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\server.py): MCP entrypoint and tool registration
• [config.py](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\config.py): environment-driven settings
• [nubra_client.py](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\nubra_client.py): Nubra client and high-level service layer
• [tools](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\tools): MCP tool modules
• [tests](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\tests): local unit tests
• [bootstrap.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\bootstrap.ps1): local environment setup
• [run_stdio.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\run_stdio.ps1): stdio launcher for MCP clients
• [run_http.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\run_http.ps1): HTTP launcher for manual testing

Requirements

• Windows with PowerShell
• Python 3.12 recommended
• Nubra account access
• internet access for Nubra APIs

Installed dependencies include:

• nubra-sdk
• nubra-talib
• TA-Lib
• pandas
• matplotlib
• vectorbt
• FastMCP stack

Setup

1. Clone the repo

git clone https://github.com/socials-zanskar/nubra-mcp-server.git
cd nubra-mcp-server

2. Bootstrap the local environment

powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1

This script:

• creates .venv
• installs dependencies
• creates .env from .env.example if missing

Alternative: install from pip

This repo also supports package-based install so users can run:

pip install nubra-mcp

After install, the user gets a nubra-mcp command.

Important caveat:

• nubra-sdk installs from PyPI
• nubra-talib is not included in the base published package yet
• vectorbt is not included in the base published package yet
• indicator tools that depend on nubra-talib are optional in package mode for now
• backtest tools that depend on vectorbt are optional in package mode for now
• the repo/bootstrap flow still installs the full indicator and backtest stack for local development

Optional package installs:

pip install "nubra-mcp[indicators]"
pip install "nubra-mcp[backtest]"
pip install "nubra-mcp[full]"

3. Fill in your local .env

Use [.env.example](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server.env.example) as the template.

Example:

PHONE=
MPIN=
NUBRA_ENV=UAT
NUBRA_DEFAULT_EXCHANGE=NSE
LOG_LEVEL=INFO
HOST=127.0.0.1
PORT=8000
MCP_PATH=/mcp
AUTH_STATE_FILE=auth_state.json

Important:

• keep NUBRA_ENV=UAT while testing trading features
• do not commit your real .env
• do not share auth_state.json

Running the MCP

Packaged command

If installed as a package, the command is:

nubra-mcp

That defaults to stdio mode so Codex can launch it directly as an MCP server.

Optional helper:

nubra-mcp init

init is not required. It only creates a local user config template under the user's home folder for convenience.

Recommended for MCP clients

powershell -ExecutionPolicy Bypass -File .\run_stdio.ps1

Recommended for HTTP testing

powershell -ExecutionPolicy Bypass -File .\run_http.ps1

Direct Python entrypoints

stdio:

.\.venv\Scripts\python.exe .\server.py --transport stdio

streamable HTTP:

.\.venv\Scripts\python.exe .\server.py --transport streamable-http

SSE:

.\.venv\Scripts\python.exe .\server.py --transport sse

Default local endpoints for HTTP mode:

• health: http://127.0.0.1:8000/health
• mcp: http://127.0.0.1:8000/mcp

Codex / MCP Client Integration

This repo includes [.mcp.json](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server.mcp.json), so repo-aware MCP clients can discover it automatically.

Typical local flow:

1. Open the repo folder in the MCP client.
2. Run bootstrap once.
3. Fill .env.
4. Reload or reopen the workspace.
5. Let the client launch [run_stdio.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\run_stdio.ps1).

If the client does not detect the server immediately, reload the workspace or restart the app.

Codex desktop app flow for GitHub/repo users

1. Clone the repo.
2. Run bootstrap.
3. Fill .env.
4. Open the repo folder in Codex desktop.
5. Reload the workspace so Codex reads .mcp.json.
6. Start chatting with:
   • Use nubra mcp and check auth status

Codex desktop app flow for pip users

1. Install the package:

pip install nubra-mcp

2. Optionally create a user-home config template:

nubra-mcp init

3. In Codex desktop, add a global MCP server entry using:
   • name: nubra-mcp
   • type: stdio
   • command: nubra-mcp
4. Reload or restart Codex desktop.
5. In a new chat, start with:
   • Use nubra mcp and check auth status

Codex CLI flow for pip users

1. Install the package:

pip install nubra-mcp

2. Register it with Codex CLI:

codex mcp add nubra-mcp --command nubra-mcp

3. Verify registration:

codex mcp list

4. Start Codex:

codex

5. In chat, start with:
   • Use nubra mcp and check auth status

Where pip users put credentials

nubra-mcp init is optional, not mandatory.

If the user does not run init, they can still connect and log in interactively through chat:

1. call auth_status
2. enter phone number when asked
3. enter OTP when asked
4. enter MPIN when asked

If the user does run nubra-mcp init, it creates a local config file under:

• C:\Users\<username>\.nubra-mcp\.env

That file is local only and should not be shared.

Authentication Flow

The intended auth flow is:

1. call auth_status
2. if login is required, ask for phone number
3. call begin_auth_flow or send_otp
4. ask for OTP
5. call verify_otp
6. ask for MPIN
7. call verify_mpin

The authenticated session is stored locally in auth_state.json and reused until Nubra expires it or the user logs out.

UAT Trading Guardrails

Trading tools are UAT-only.

Allowed only in UAT:

• preview_uat_order
• place_uat_order
• modify_uat_order
• cancel_uat_order
• square_off_uat_position
• place_uat_options_strategy
• place_uat_named_option_strategy

Blocked in PROD:

• all order placement
• all modify/cancel actions
• all square-off actions
• all strategy execution actions

Recommended trading flow:

1. use preview_uat_order
2. show the clean preview table to the user
3. confirm the order details
4. place the order with place_uat_order

The preview includes:

• environment
• symbol
• ref id
• side
• quantity
• order type
• price type
• order price
• product
• validity
• current price
• warnings if the limit is marketable

Export and Report Features

This MCP can save artifacts locally on the user’s machine.

Examples:

• historical CSV exports
• HTML portfolio reports
• PNG portfolio dashboards
• HTML backtest reports
• PNG backtest equity curves

Exports are written under:

• [artifacts](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\artifacts)

For small outputs, tools can also return:

• preview_rows
• preview_columns
• preview_mode

That lets the chat render a small table inline while still providing a full downloadable file path.

Indicator and Backtest Features

nubra-talib

Indicator tools use nubra-talib.

In repo mode, it is installed through [requirements.txt](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\requirements.txt).

In package mode, nubra-talib is currently optional and not bundled into the base pip install nubra-mcp path yet.

Example uses:

• summarize indicators for one symbol
• scan multiple symbols for RSI thresholds
• scan EMA/SMA crossovers

vectorbt

Backtesting tools use vectorbt.

In package mode, vectorbt is currently optional and not bundled into the base pip install nubra-mcp path yet.

Currently supported examples:

• moving average crossover backtest
• RSI backtest
• HTML backtest export
• equity curve image export

Example Prompts

Auth

• Check auth status
• Start authentication for phone [phone]
• Verify OTP 123456
• Verify MPIN 2004

Quotes and history

• Get quote for RELIANCE
• Export historical data as CSV for RELIANCE on 1d candles from 2026-02-01 to 2026-03-01
• Give me a historical chart summary for RELIANCE on 1d candles

Portfolio

• Generate a portfolio report
• Export my portfolio report as HTML
• Export my portfolio report as an image dashboard

Indicators

• Summarize symbol indicators for RELIANCE on 1d candles with RSI 14 and EMA 20
• Scan indicator threshold for RELIANCE, TCS, INFY with RSI >= 60

Backtesting

• Run a moving average crossover backtest for RELIANCE on 1d candles with fast_window 20 and slow_window 50
• Export a backtest report as HTML for RELIANCE using strategy_type ma_crossover

UAT trading

• Preview a UAT order for RELIANCE with quantity 1, limit price 1500, and CNC
• Place a UAT order for RELIANCE with quantity 1, limit price 1500, and CNC
• Modify UAT order 12345 with a new price
• Cancel UAT order 12345

Local Validation

Import smoke test

.\.venv\Scripts\python.exe -c "import server; print('server-import-ok')"

Run tests

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Public Release Checklist

Before pushing this repo publicly:

1. make sure .env is not committed
2. make sure auth_state.json is not committed
3. make sure artifacts/ is ignored
4. make sure your real credentials are removed from local screenshots, logs, and examples
5. verify NUBRA_ENV defaults to UAT in examples
6. test preview_uat_order and place_uat_order
7. verify PROD trading is still blocked

Notes

• Start with UAT while validating the tool surface.
• If a client says trading is disabled, it may be reading an older workspace or worktree copy of the repo.
• The main intended repo path should be used, not a stale Codex worktree, when testing the latest changes.
• This repo is designed to be extended; the tool surface is intentionally modular.