Trade, check margins, and review orders, portfolio, and fundamentals on Upstox — without leaving your agent.
A Model Context Protocol (MCP) server that exposes Upstox's API for retrieving user profile and fund details, estimating trade margins, and reviewing orders, portfolio, company fundamentals, and profit and loss.
Overview
The mewcp-upstox MCP Server provides:
Authenticated user profile and fund/margin balance retrieval
Pre-trade margin estimation across multiple instruments in a single call
Order book and historical trade record lookups with date-range filtering
Portfolio position and holding retrieval
Company fundamentals lookup (profile and balance sheet) by ISIN
Trade-wise profit and loss reporting by segment and financial year
Perfect for:
Trading assistants that need to check available balance before placing orders
Portfolio and risk tools that estimate margin requirements ahead of execution
Reporting agents that reconcile the day's orders, trade history, or profit and loss
Research tools that pull company fundamentals alongside portfolio data
Tools
Retrieves the authenticated user's account profile — email, exchanges, products, broker, user ID, order types, and account status flags. Does not include fund, margin, or balance data.
Retrieves the user's current cash and pledged margin balance, broken down into amounts available and unavailable to trade. Unavailable daily from 12:00 AM to 5:30 AM IST, when it returns a 423 error instead of data.
Inputs: None
Output data schema:
{ available_to_trade: { total: number | null; cash_available_to_trade: { total: number | null; cash: { opening_balance: number | null; added_today: number
Computes and returns the estimated margin required for a proposed trade of up to 20 instruments. Does not place, modify, or persist any order.
Inputs:
- `instruments` (array of object, required) — Instruments to request margin details for (maximum 20 per request). Each item requires `instrument_key`, `quantity` (a multiple of lot size), `product` (`I`, `D`, `CO`, or `MTF`), and `transaction_type` (`BUY` or `SELL`); `price` is optional.
each item in instruments:
- `instrument_key` (string, required) — Key of the instrument.- `quantity` (integer, required) — Order quantity — must be a multiple of lot size.- `product` (string, required) — Product the order would use.- `transaction_type` (string, required) — BUY or SELL.
Retrieves all orders placed during the current trading day, each with its latest status. Does not return orders from previous days — those are cleared at end of session.
Retrieves executed trade records for a given date range and optional segment, limited to at most the last 3 financial years.
Inputs:
- `start_date` (string, required) — Start of the date range, YYYY-mm-dd. Must be within the last 3 financial years.- `end_date` (string, required) — End of the date range, YYYY-mm-dd. Must be within the last 3 financial years and >= start_date.- `page_number` (integer, required) — Page number, starting from 1.- `page_size` (integer, required) — Page size for pagination (1-5000).- `segment` (string, optional, default: null) — Segment to filter by. If omitted, all segments are included. Possible values: EQ (Equity), FO (Futures and Options), COM (Commodity), CD (Currency Derivatives), MF (Mutual Funds).
Retrieves the positions currently held in the account and returns them as a list. Positions remain in this portfolio until sold or, for derivatives, until expiry (max three months); equity positions carried overnight are automatically shifted to the holdings portfolio the following trading day.
Inputs: None
Output data schema:
{ positions: { exchange: string | null; multiplier: number | null; value: number | null; pnl: number | null; product
Retrieves the holdings currently held in the account and returns them as a list. A holding stays in place indefinitely — it's only removed when divested, delisted, or modified by exchange action.
Retrieves the company profile for a given ISIN — a business description, its sector, and the sector's total market capitalisation in both Indian Rupees and US Dollars.
Inputs:
- `isin` (string, required) — ISIN of the company, e.g. INE002A01018.
Retrieves balance sheet statement data for a given ISIN — summary total assets and liabilities by reporting period, plus an optional detailed line-item breakdown when fs=true. All monetary values are in Indian Rupees (Crore).
Inputs:
- `isin` (string, required) — ISIN of the company, e.g. INE002A01018.- `type` (string, optional, default: null) — Financial statement type. Possible values: consolidated, standalone. Defaults to consolidated when omitted.- `fs` (boolean, optional, default: null) — When true, includes a detailed line-item breakdown in the full_statement field of the response. Omit or set to false to exclude it.
Retrieves metadata for the trade-wise profit and loss report for a given segment and financial year, optionally narrowed to a date range. Returns the total trade count and the maximum page_size accepted by get_profit_loss_report.
Inputs:
- `segment` (string, required) — Segment to request data for. Possible values: EQ (Equity), FO (Futures and Options), COM (Commodity), CD (Currency Derivatives).- `financial_year` (string, required) — Financial year to request data for — concatenation of the last 2 digits of the from-year and to-year, e.g. 2021-2022 -> 2122.- `from_date` (string, optional, default: null) — Start of the date range, dd-mm-yyyy. Must fall within the same financial year as financial_year. Omit to cover the full financial year.- `to_date` (string, optional, default: null) — End of the date range, dd-mm-yyyy. Must fall within the same financial year as financial_year, and >= from_date. Omit to cover the full financial year.
Retrieves the trade-wise profit and loss report entries for a given segment and financial year, optionally narrowed to a date range, paginated by page_number and page_size. The maximum accepted page_size is returned as data.page_size_limit by get_report_meta_data.
Inputs:
- `segment` (string, required) — Segment to request data for. Possible values: EQ (Equity), FO (Futures and Options), COM (Commodity), CD (Currency Derivatives).- `financial_year` (string, required) — Financial year to request data for — concatenation of the last 2 digits of the from-year and to-year, e.g. 2021-2022 -> 2122.- `page_number` (integer, required) — Page number, starting from 1.- `page_size` (integer, required) — Page size for pagination (max 5000; the actual max for this account is obtained from get_report_meta_data's data.page_size_limit).- `from_date` (string, optional, default: null) — Start of the date range, dd-mm-yyyy. Must fall within the same financial year as financial_year. Omit to cover the full financial year.- `to_date` (string, optional, default: null
API Parameters Reference
Every tool returns the same top-level envelope. Only data varies per tool.
segment — Trade segment. Possible values: EQ (Equity), FO (Futures and Options), COM (Commodity), CD (Currency Derivatives) in get_report_meta_data and get_profit_loss_report; get_trade_history additionally accepts MF (Mutual Funds) and treats the parameter as optional (all segments included when omitted).
page_number — Page number, starting from 1. Used in get_trade_history and get_profit_loss_report.
page_size — Page size for pagination. get_trade_history accepts 1-5000; get_profit_loss_report accepts up to 5000, with the account-specific maximum returned as by .
Instrument Key:
upstox instrument identifier used to reference a specific tradable instrument.Used as `instrument_key` in `get_margin_details`.
product:
one of: I, D, CO, MTF.Used as `product` in `get_margin_details`.
isin:
international Securities Identification Number for a company.Example: INE002A01018Used as `isin` in `get_company_profile` and `get_balance_sheet`.
Troubleshooting
Cause: API key not provided in request headers or incorrect format
Solution:
Verify Authorization: Bearer YOUR_API_KEY and X-Mewcp-Credential-Id: CREDENTIAL-ID headers are present
Check API key is active in your MewCP account
Cause: API calls have exceeded your request limits
Solution:
Check credit usage in your Curious Layer dashboard
Upgrade to a paid plan or add credits for higher limits
Contact support for credit adjustments
Cause: No Upstox credential linked to your account
Solution:
Go to Credentials in your MewCP dashboard
Connect your Upstox account (OAuth) or add your API key (static)
Retry the request with the correct X-Mewcp-Credential-Id header
Cause: JSON payload is invalid or missing required fields
{ trades_count: number | null; page_size_limit: number | null;}
) — End of the date range, dd-mm-yyyy. Must fall within the same financial year as financial_year, and >= from_date. Omit to cover the full financial year.
output data schema:
{ entries: { quantity: number | null; isin: string | null; scrip_name: string | null; trade_type: string | null; buy_date: string | null; buy_average: number | null; sell_date: string | null; sell_average: number | null; buy_amount: number | null; sell_amount: number | null; }[]; meta_data: { page_number: number | null; page_size: number | null; } | null;}
financial_year — Financial year to request data for — concatenation of the last 2 digits of the from-year and to-year, e.g. 2021-2022 -> 2122. Used in get_report_meta_data and get_profit_loss_report.
from_date / to_date — Date range, dd-mm-yyyy, that must fall within the given financial_year; to_date >= from_date. Omit both to cover the full financial year. Used in get_report_meta_data and get_profit_loss_report.
isin — ISIN of the company, e.g. INE002A01018. Used in get_company_profile and get_balance_sheet.
date (YYYY-mm-dd):
calendar date string, e.g. 2026-01-15.Used for `start_date` and `end_date` in `get_trade_history`.
date (dd-mm-yyyy):
calendar date string, e.g. 15-01-2026.Used for `from_date` and `to_date` in `get_report_meta_data` and `get_profit_loss_report`.
financial Year:
concatenation of the last 2 digits of the from-year and to-year.Example: 2021-2022 -> 2122Used as `financial_year` in `get_report_meta_data` and `get_profit_loss_report`.
