Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TradeMCP what's the RSI for RELIANCE and my portfolio risk?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that exposes trading analytics — technical indicators, portfolio state, risk metrics, and backtest results — as tools an LLM agent can call. Built to demonstrate protocol-level MCP understanding, not just API wrapping.
The defining design choice: read operations are open; write operations (placing trades) sit behind a human-in-the-loop approval gate. Phase 1 (this repo) ships the read-only surface and the architecture that makes the read/write split clean.
Most MCP portfolio projects wrap a public API in a decorator. This one is built around the questions that actually come up when you put an agent in front of something that can move money:
What happens when the model sends a hallucinated symbol or malformed arguments?
How do you stop an agent from doing something irreversible?
How do you keep tool outputs small enough to not blow the context window?
How do you swap simulated data for a live brokerage without rewriting the tools?
See DESIGN.md for the full decision record.
Related MCP server: FinClaw
┌──────────────┐ MCP (stdio / streamable HTTP) ┌────────────────────┐
│ LLM client │ ───────────────────────────────► │ TradeMCP server │
│ (Claude etc.)│ ◄─────────────────────────────── │ (server.py) │
└──────────────┘ tool calls / results └─────────┬──────────┘
│ depends on interface
▼
┌──────────────────────────────┐
│ MarketDataProvider (ABC) │
├──────────────────────────────┤
│ SimulatedProvider (default) │
│ KiteProvider (Phase 2) │ ← live AutoTrade Bot
└──────────────────────────────┘Module | Responsibility |
| Protocol/tool layer: validate input → call provider → format output |
| Data layer behind an abstract interface (the swap point for live data) |
| Pydantic input schemas — the first line of defense against bad LLM input |
| Shared markdown/JSON formatting (context-efficient output) |
| Centralized, actionable error messages |
The tool layer depends on the MarketDataProvider interface, never on a concrete data source. That dependency-inversion boundary is what lets the same server run on simulated data in CI and live data in production.
Tool | Purpose |
| Latest RSI / EMA / MACD / ATR + signal for a symbol |
| Holdings, cash, equity, unrealized P&L |
| Concentration, beta, VaR, Sharpe, drawdown, circuit breakers |
| Paginated list of backtest runs (discover run IDs) |
| Full metrics for one run |
Every tool is annotated readOnlyHint: true and supports both markdown (default, human-readable) and json (structured) output.
# 1. Install
pip install -e ".[dev]"
# 2. Run the test suite
pytest
# 3. Run the server (stdio transport, the default)
python -m trade_mcp.server
# Or over HTTP for remote clients:
TRADE_MCP_TRANSPORT=streamable_http TRADE_MCP_PORT=8000 python -m trade_mcp.servernpx @modelcontextprotocol/inspector python -m trade_mcp.serverAdd to claude_desktop_config.json:
{
"mcpServers": {
"trade-mcp": {
"command": "python",
"args": ["-m", "trade_mcp.server"],
"cwd": "/absolute/path/to/trade-mcp/src"
}
}
}Then ask: "What's the RSI on Reliance, and how concentrated is my portfolio?"
The default SimulatedMarketDataProvider returns deterministic data derived from a hash of each input, so demos and tests are fully reproducible with zero credentials. Wiring in the live AutoTrade Bot backend means implementing the five MarketDataProvider methods in a new class and changing one line in server.py.
Phase 1 — Read-only analytics surface, provider abstraction, tests
Phase 2 — trade_place_order behind a human approval gate (Telegram confirmation + audit log)
Phase 3 — Rate limiting, response caching, retries
Phase 4 — Multi-server client demonstrating tool discovery/orchestration
Phase 5 — Live KiteMarketDataProvider wrapping the real trading bot
MIT
Get full metrics for a single backtest run by its ID.
Use trade_list_backtests first to find a valid run_id, then call this for the detailed performance breakdown (returns, Sharpe/Sortino, drawdown, win rate, profit factor, capital curve endpoints).
Args: params (GetBacktestInput): Validated input containing: - run_id (str): Run identifier from trade_list_backtests - response_format (ResponseFormat): "markdown" (default) or "json"
Returns: str: Markdown summary, or JSON with this schema: { "run_id": str, "strategy": str, "symbol": str, "ran_at": str, "period": {"start": str, "end": str}, "metrics": { "total_return_pct": float, "annualized_return_pct": float, "sharpe_ratio": float, "sortino_ratio": float, "max_drawdown_pct": float, "win_rate_pct": float, "total_trades": int, "profit_factor": float }, "starting_capital": float, "ending_capital": float } On failure (including unknown run_id): "Error: "
Examples: - "How did bt_ema_crossover_reliance_0427 perform?" -> that run_id - Don't guess run IDs — list them first with trade_list_backtests.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: it explains the output format (markdown or JSON based on response_format), returns a detailed JSON schema, and describes error behavior (returns 'Error: <actionable message>' for failure). Annotations already indicate read-only, non-destructive, idempotent, which is consistent. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: it starts with the purpose, then provides usage steps, parameter details, return schema, and examples. Every sentence adds value without redundancy. It is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (single parameter with nested options), schema coverage of 0%, and presence of output schema in description, the description is complete. It covers what the tool does, how to use it, input parameters, output format and schema, error handling, and examples. No gaps for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema description coverage being listed as 0%, the description thoroughly explains both parameters: run_id ('Run identifier from trade_list_backtests') and response_format ('markdown' default) with context and examples. It adds meaning beyond the schema's property descriptions by showing usage and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get full metrics for a single backtest run by its ID.' It uses a specific verb ('Get') and resource ('backtest run by ID'), and distinguishes from sibling tools like trade_list_backtests by advising to use that tool first to obtain a valid run_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use trade_list_backtests first to find a valid run_id, then call this for the detailed performance breakdown.' It also warns against guessing run IDs and tells when not to use (e.g., don't use for listing). This clearly differentiates from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the latest technical indicators for a single NSE symbol.
Returns a snapshot of common momentum/trend indicators (RSI, EMAs, MACD, ATR) plus a derived bullish/bearish signal. Read-only; computes nothing on live capital.
Args: params (GetIndicatorsInput): Validated input containing: - symbol (str): NSE ticker, case-insensitive (e.g. "RELIANCE") - response_format (ResponseFormat): "markdown" (default) or "json"
Returns: str: Markdown summary, or JSON with this schema: { "symbol": str, # normalized uppercase ticker "as_of": str, # ISO 8601 UTC timestamp "last_price": float, "indicators": { "rsi_14": float, "ema_20": float, "ema_50": float, "macd": float, "macd_signal": float, "macd_histogram": float, "atr_14": float }, "signal": str # "bullish" | "bearish" } On failure: "Error: "
Examples: - "What's the RSI on Infosys?" -> symbol="INFY" - "Is Reliance bullish right now?" -> symbol="RELIANCE" - Don't use to place a trade — this tool is read-only analytics.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds details on the read-only behavior ('computes nothing on live capital') and outlines the exact return schema and error handling. It does not mention rate limits or authentication, but these are likely system-level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear summary, structured Args/Returns, examples, and a usage note. It is a bit lengthy but every section adds value. The return schema could be omitted if the output schema were visible, but the text version is helpful for quick reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single symbol, read-only) and the wealth of annotations and input schema, the description covers all necessary aspects: purpose, input parameters with defaults, output format and schema, error handling, and usage examples. No obvious gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description reiterates parameter meanings (symbol, response_format) with examples like case-insensitivity and default format. Given that the input schema already contains descriptions and coverage is 0%, the description compensates adequately by adding practical context, though it does not introduce new constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the latest technical indicators for a single NSE symbol, with specific verb 'Get' and resource 'technical indicators'. It distinguishes from siblings (backtesting, portfolio, risk) by focusing on real-time indicator snapshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises not to use the tool for placing trades, reinforcing its read-only nature. Examples illustrate appropriate queries, and the sibling tools cover different domains, making usage context clear. However, no direct comparison with specific sibling tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current portfolio: holdings, cash, equity, and unrealized P&L.
Read-only snapshot of all open positions with per-position and aggregate profit/loss.
Args: params (PortfolioInput): Validated input containing: - response_format (ResponseFormat): "markdown" (default) or "json"
Returns: str: Markdown summary, or JSON with this schema: { "as_of": str, # ISO 8601 UTC timestamp "cash_balance": float, "invested": float, "market_value": float, "total_equity": float, "unrealized_pnl": float, "position_count": int, "positions": [ { "symbol": str, "quantity": int, "avg_cost": float, "last_price": float, "invested": float, "market_value": float, "unrealized_pnl": float, "unrealized_pnl_pct": float } ] } On failure: "Error: "
Examples: - "How is my portfolio doing?" -> default markdown - "Give me my positions as JSON" -> response_format="json"
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint, idempotentHint, and destructiveHint false, which align with the description's 'Read-only snapshot' statement. The description further clarifies output structure (markdown/json) and error messages, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate sections for description, arguments, returns, and examples. Every sentence adds value, and the front-loaded purpose sentence immediately communicates the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all relevant aspects: purpose, single parameter, output schema in detail, error behavior, and usage examples. With no missing elements, it fully informs an AI agent for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter (response_format) is explained in the description with defaults and examples, complementing the schema's description. Although schema description coverage is listed as 0%, the actual schema includes descriptions, and the tool description enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it retrieves the current portfolio with holdings, cash, equity, and unrealized P&L. It clearly distinguishes from sibling tools like trade_get_backtest or trade_get_indicators by focusing on the live portfolio snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete examples ('How is my portfolio doing?', 'Give me my positions as JSON') that illustrate typical usage. Does not explicitly mention when not to use it, but the examples sufficiently convey appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregate risk metrics for the current portfolio.
Surfaces concentration, beta, Value-at-Risk, Sharpe, drawdown, risk-budget usage, and any open circuit breakers. Read-only.
Args: params (PortfolioRiskInput): Validated input containing: - response_format (ResponseFormat): "markdown" (default) or "json"
Returns: str: Markdown summary, or JSON with this schema: { "as_of": str, # ISO 8601 UTC timestamp "total_equity": float, "max_position_concentration_pct": float, "portfolio_beta": float, "value_at_risk_95_1d": float, "sharpe_ratio_30d": float, "max_drawdown_pct": float, "open_circuit_breakers": [str], "risk_budget_used_pct": float } On failure: "Error: "
Examples: - "How concentrated is my portfolio?" -> read concentration_pct - "What's my 1-day VaR?" -> read value_at_risk_95_1d
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds behavioral context: it discloses the tool is read-only, lists the metrics returned, describes the output format and failure response. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with first sentence, bullet points, Args/Returns sections, and examples. Every sentence provides useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, metrics, read-only nature, parameter details, output schema, failure handling, and usage examples. It is fully complete given the tool's complexity and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes descriptions for params and response_format. The description adds value by explaining the default output format ('markdown') and the structure of the JSON response. It clarifies what the single parameter does beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets aggregate risk metrics for the current portfolio and lists specific metrics (concentration, beta, VaR, etc.). It distinguishes from sibling tools like trade_get_backtest and trade_get_portfolio by focusing on risk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides example questions that trigger the tool, but does not explicitly state when to avoid it or mention alternatives. The context and sibling names help, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available backtest runs, most useful for discovering run IDs.
Returns a paginated list of run summaries. Pair this with trade_get_backtest to drill into a specific run's full metrics.
Args: params (ListBacktestsInput): Validated input containing: - limit (Optional[int]): Max runs to return, 1-50 (default 10) - offset (Optional[int]): Runs to skip for pagination (default 0) - response_format (ResponseFormat): "markdown" (default) or "json"
Returns: str: Markdown summary, or JSON with this schema: { "total": int, # total runs available "count": int, # runs in this page "offset": int, # current offset "items": [ { "run_id": str, "strategy": str, "symbol": str, "ran_at": str, "total_return_pct": float, "sharpe_ratio": float } ], "has_more": bool, "next_offset": int | null # offset for the next page, if any } On failure: "Error: "
Examples: - "What backtests have I run?" -> default page - "Show me the next 10 backtests" -> offset=10
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds valuable behavioral context: pagination behavior (limit/offset), response format options (markdown/json), and error format. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured: one-line purpose, then details, args, returns, and examples. Every sentence adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, output schema provided), the description covers all necessary aspects: purpose, usage guidelines, parameter details, return format, error handling, and examples. It is fully complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions exist for each parameter, but the description adds default values (limit=10, offset=0, response_format='markdown') and explains the output format schema. The 'Args' section re-inforces parameter meaning, and the 'Returns' section details the JSON structure, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List available backtest runs, most useful for discovering run IDs' and distinguishes from sibling 'trade_get_backtest' by suggesting pairing. The verb 'list' is specific and the resource 'backtest runs' is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to pair with 'trade_get_backtest' for detailed metrics and gives concrete examples (default page vs offset=10). It tells the agent when to use pagination, though it doesn't explicitly state when not to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0trade_get_backtesttrade_get_indicatorstrade_get_portfoliotrade_get_portfolio_risktrade_list_backtestsScored across 5 tools
Each tool targets a distinct area: backtest details, indicators, portfolio snapshot, portfolio risk, and backtest listing. No overlap in functionality.
All tool names follow a consistent verb_noun pattern prefixed with 'trade_' (e.g., trade_get_backtest, trade_list_backtests).
5 tools cover the core analytical needs of a trading server: portfolio overview, risk assessment, indicators, and backtesting. Well-scoped.
The server focuses on read-only analytics; missing order placement or historical price data, but core portfolio, risk, indicators, and backtest coverage is solid.
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
Research-only MCP server: your AI as a quant research desk. 90 tools, no trades, no brokers.
Trade across 22+ exchanges and brokers from any MCP-capable AI agent, no install required.
