# Canli Paper Trading

An MCP server that lets an agent trade an Alpaca paper account while keeping every order behind pre-trade checks. Your keys stay in your own environment.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: arhancanli
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/arhancanli/canlicapital/tree/HEAD/mcp-paper
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/canli-paper-trading

## What it does

The server runs locally over stdio. An agent can read the account, turn target weights into orders, run the checks and send what passes. Each order is measured against your limits, the market clock and a kill switch. Orders that clear the checks get a five-minute token, and a token is the only way to send.

Your limits sit in `CANLI_HOME/limits.json` (`~/.canli` by default): order notional cap, position fraction, gross and net caps, allowed order types. A call may tighten them for a single preview, never relax them. While a file named `KILL` is present in that directory, previews fail and sends are refused. A token is bound to the exact orders previewed, so changing a quantity invalidates it. Restart the server and old tokens stop verifying.

Paper is the only mode. Live keys are rejected and there is no host for real trading in the package. Alpaca simulates paper fills without queue position or market impact, so a strategy that survives on paper has not yet proven itself in live markets. You need paper Alpaca keys (the id starts with `PK`) and Node.js to run it through `npx`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ALPACA_PAPER_KEY_ID`, `ALPACA_PAPER_SECRET_KEY`, `CANLI_HOME` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ALPACA_PAPER_KEY_ID=<ALPACA_PAPER_KEY_ID> --env ALPACA_PAPER_SECRET_KEY=<ALPACA_PAPER_SECRET_KEY> --env CANLI_HOME=<CANLI_HOME> --transport stdio mcp-paper -- npx -y canli-paper-trading-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add mcp-paper --env ALPACA_PAPER_KEY_ID=<ALPACA_PAPER_KEY_ID> --env ALPACA_PAPER_SECRET_KEY=<ALPACA_PAPER_SECRET_KEY> --env CANLI_HOME=<CANLI_HOME> -- npx -y canli-paper-trading-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-paper": {
            "command": "npx",
            "args": [
                "-y",
                "canli-paper-trading-mcp"
            ],
            "env": {
                "ALPACA_PAPER_KEY_ID": "<ALPACA_PAPER_KEY_ID>",
                "ALPACA_PAPER_SECRET_KEY": "<ALPACA_PAPER_SECRET_KEY>",
                "CANLI_HOME": "<CANLI_HOME>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-paper": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "canli-paper-trading-mcp"
            ],
            "env": {
                "ALPACA_PAPER_KEY_ID": "<ALPACA_PAPER_KEY_ID>",
                "ALPACA_PAPER_SECRET_KEY": "<ALPACA_PAPER_SECRET_KEY>",
                "CANLI_HOME": "<CANLI_HOME>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ALPACA_PAPER_KEY_ID=<ALPACA_PAPER_KEY_ID> -e ALPACA_PAPER_SECRET_KEY=<ALPACA_PAPER_SECRET_KEY> -e CANLI_HOME=<CANLI_HOME> mcp-paper npx -y canli-paper-trading-mcp
```
Replace <…> with your own values

## When to use it
- let an agent trade a paper account without giving up control
- check orders against your own limits before anything is sent
- turn backtest target weights into whole-share orders
- halt trading by dropping a `KILL` file
- get a signed attestation of which orders were checked and against which limits

## Example prompts
- Show my paper account: equity, positions, open orders and the market clock.
- Cancel the open order with that id.

## Similar
- [Polymarket Paper Trader](https://affpapa.org/en/nevibecode/mcp/polymarket-paper-trader.md) — MCP server · ★ 492
- [portfolio-manager](https://affpapa.org/en/nevibecode/skills/portfolio-manager.md) — skill · 3900 installs
- [breakout-trade-planner](https://affpapa.org/en/nevibecode/skills/breakout-trade-planner.md) — skill · 3100 installs
- [trading-wisdom](https://affpapa.org/en/nevibecode/skills/trading-wisdom.md) — skill · 800 installs
- [predexon-prediction-market-trading-1-5-teneo](https://affpapa.org/en/nevibecode/skills/predexon-prediction-market-trading-1-5-teneo.md) — skill · 478 installs
- [copy-trading](https://affpapa.org/en/nevibecode/skills/copy-trading.md) — skill · 439 installs

From the same set: [arhancanli/canlicapital](https://affpapa.org/en/nevibecode/by/arhancanli/canlicapital.md) — 4 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md