# NinjaTrader 8 MCP Server

Claude Code integration for NinjaTrader 8. Gives Claude direct access to accounts, positions,
orders, market data, charts, and strategy management through a NinjaScript Add-On running
inside NT8.

## Architecture

```
Claude Code (claude.ai/code)
     | stdio JSON-RPC 2.0 (MCP protocol)
     v
src/server.js  (Node.js MCP server — 26 tools)
     | HTTP  localhost:7890
     v
nt8-addon/McpBridgeAddon.cs  (NinjaScript Add-On running inside NT8.exe)
     | NT8 internal API
     +-- Account.All             -> accounts, balances, P&L
     +-- Order.CreateOrder()     -> place / cancel / modify orders
     +-- Account.Positions       -> open positions
     +-- Instrument.All          -> market data, quotes, instrument search
     +-- ChartControl            -> chart state, instrument, reload
     +-- Strategy management     -> enumerate and stop running strategies
```

**Key difference from browser-based MCPs:** NT8 has no external HTTP API.
`McpBridgeAddon.cs` is a NinjaScript Add-On that runs *inside* NT8's process and bridges
its internal .NET APIs to an HTTP listener on `localhost:7890`. Without it, nothing works.

---

## Features (26 MCP tools)

| Category | Tools |
|----------|-------|
| Health | `nt_health_check` |
| Connections | `nt_connection_status` |
| Accounts | `nt_accounts`, `nt_account_balance`, `nt_account_info` |
| Positions | `nt_positions`, `nt_position` |
| Orders | `nt_orders`, `nt_place_order`, `nt_modify_order`, `nt_cancel_order`, `nt_cancel_all_orders`, `nt_close_position`, `nt_flatten_all` |
| Market Data | `nt_quote`, `nt_instrument_info`, `nt_instrument_search`, `nt_bars`, `nt_depth` |
| Charts | `nt_charts`, `nt_chart_state`, `nt_chart_instrument`, `nt_chart_reload` |
| Strategies | `nt_strategies_running`, `nt_strategy_stop` |
| Indicators | `nt_indicator_values` |

---

## Quick Setup

### Prerequisites
- NinjaTrader 8 (any account — Sim, Demo, or Live)
- Node.js 18+
- Claude Code

### 1. Install the Add-On

Copy `McpBridgeAddon.cs` to NT8's custom Add-Ons folder:

```powershell
# Adjust the path to match your user directory
Copy-Item "nt8-addon\McpBridgeAddon.cs" `
    "$env:USERPROFILE\OneDrive\Documents\NinjaTrader 8\bin\Custom\AddOns\McpBridgeAddon.cs" -Force
```

Or copy to:
```
%USERPROFILE%\Documents\NinjaTrader 8\bin\Custom\AddOns\McpBridgeAddon.cs
```

### 2. Compile in NT8

1. Open NinjaTrader 8
2. Control Center menu: **New -> NinjaScript Editor**
3. In the left tree, expand **Add-Ons** -> click **McpBridgeAddon**
4. Press **F5** to compile
5. If an authorization dialog appears ("NinjaTrader has detected new add-on(s)"), click **Yes**
   NT8 will restart and auto-enable the Add-On.
6. If the port doesn't come up automatically: **Tools -> Add-Ons** -> check **McpBridgeAddon** -> OK

### 3. Verify the Add-On is running

```powershell
curl.exe http://localhost:7890/api/health
# Expected: {"status":"ok","version":"1.2.0","port":7890,"accounts":N}
```

### 4. Install the MCP server

```bash
npm install
```

### 5. Register with Claude Code

Add to `~/.claude/settings.json` under `mcpServers`:

```json
"ninjatrader": {
  "command": "node",
  "args": ["C:/path/to/ninjatrader-mcp/src/server.js"],
  "env": {
    "NINJATRADER_MODE": "local",
    "NINJATRADER_LOCAL_URL": "http://localhost:7890"
  }
}
```

Restart Claude Code, then verify:
```
Use nt_health_check to verify NinjaTrader is connected.
```

---

## Automated Boot (optional)

`scripts/nt8-full-boot.ps1` automates the entire cold-start sequence:
1. Launch NT8
2. Complete Google OAuth login (reads credentials from `.env`)
3. Select Simulation mode
4. Open NinjaScript Editor -> compile McpBridgeAddon
5. Detect and fix compile errors before proceeding
6. Enable Add-On via Tools -> Add-Ons
7. Verify port 7890 + run health check

```powershell
cp .env.example .env   # fill in NINJATRADER_USERNAME
powershell -ExecutionPolicy Bypass -File scripts\nt8-full-boot.ps1
```

---

## API Reference

The Add-On exposes 26 HTTP endpoints on `localhost:7890`. The MCP server wraps these as tools.

### Key endpoints

```
GET  /api/health
GET  /api/connection/status
GET  /api/accounts
GET  /api/account/{id}/balance
GET  /api/account/{id}
GET  /api/positions
POST /api/order/place
POST /api/order/cancel
POST /api/order/modify
GET  /api/quote/{symbol}          -- symbol format: "NQ 09-26" not "NQ DEC25"
GET  /api/instrument/{symbol}
GET  /api/instruments/search?q=NQ
GET  /api/bars/{symbol}?period=1&type=minute
GET  /api/orders
POST /api/order/closeposition
POST /api/order/flattenall
GET  /api/charts
GET  /api/chart/state
POST /api/chart/instrument
POST /api/chart/reload
GET  /api/strategies/running
POST /api/strategy/stop
GET  /api/indicator/{symbol}/{name}
GET  /api/depth/{symbol}
```

### Place order

```bash
curl -X POST http://localhost:7890/api/order/place \
  -H "Content-Type: application/json" \
  -d '{"accountId":"Sim101","instrument":"NQ 09-26","action":"Buy","orderType":"Market","quantity":1}'
```

**Field names:** `accountId` (not `account`), `instrument` (not `symbol`)

**NT8 symbol format:** Use `NQ 09-26` (futures month-year code). The current front month
as of mid-2026 is `NQ 09-26`. Quarterly rolls change this in March/June/September/December.

---

## Accounts (Simulation)

| Account | Connection | Cash |
|---------|-----------|------|
| Sim101 | Simulation | $100,000 |
| DEMO7847095 | Simulation | $50,000 |
| Backtest | - | $100,000 |
| Playback101 | - | $0 |

---

## Environment Variables

Copy `.env.example` to `.env`:

```env
NINJATRADER_MODE=local
NINJATRADER_LOCAL_URL=http://localhost:7890
NINJATRADER_USERNAME=your@gmail.com
NINJATRADER_ACCOUNT=simulated
```

`NINJATRADER_USERNAME` and `NINJATRADER_ACCOUNT` are only used by the boot automation script.
The MCP server itself only needs `NINJATRADER_MODE` and `NINJATRADER_LOCAL_URL`.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `Connection refused` on port 7890 | NT8 not running or Add-On disabled | Start NT8, enable Add-On via Tools -> Add-Ons |
| Compile error in NinjaScript Editor | API mismatch (rare) | See `nt8-addon/McpBridgeAddon.cs` header comments |
| `Account not found` | No broker connection | Connect Simulation account in NT8 Connections menu |
| Quote returns zeros | Market closed or no subscription | Normal on weekends; open a chart for that symbol |
| Order state: Rejected | Market hours (Sim broker) | Expected outside RTH; will fill when market opens |
| `instrument is required` | Wrong field name | Use `instrument` not `symbol` in order body |

---

## File Structure

```
ninjatrader-mcp/
+-- src/
|   +-- server.js          MCP server (26 tools, JSON-RPC 2.0 over stdio)
|   +-- api.js             NT8 HTTP API client
+-- nt8-addon/
|   +-- McpBridgeAddon.cs  NinjaScript Add-On (runs inside NT8.exe)
|   +-- INSTALL.md         Add-On installation guide
+-- scripts/
|   +-- nt8-full-boot.ps1  Full cold-start automation (launch -> login -> compile -> verify)
|   +-- nt8-enable-addon.ps1  Standalone: enable Add-On via Tools -> Add-Ons
|   +-- nt8-mcp-start.ps1    Standalone: start MCP server (assumes NT8 already running)
+-- .env.example           Environment variable template
+-- package.json
+-- README.md
+-- SETUP_GUIDE.md         Extended setup walkthrough
```

---

## License

MIT