Canli Paper Trading — Claude Code MCP server: Alpaca 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.
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-mcpWhat Canli Paper Trading 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.
What it helps with
- 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
KILLfile - get a signed attestation of which orders were checked and against which limits
Example prompts for the agent
- Show my paper account: equity, positions, open orders and the market clock.
- Cancel the open order with that id.
How to install Canli Paper Trading
Platform CLI
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-mcpReplace <…> with your own values
Platform CLI
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-mcpReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Canli Paper Trading
How do I install Canli Paper Trading in Claude Code?
Run claude mcp add canli-paper -e ALPACA_PAPER_KEY_ID=PK... -e ALPACA_PAPER_SECRET_KEY=... -- npx -y canli-paper-trading-mcp with your own paper Alpaca keys.
What does Canli Paper Trading do?
It exposes four tools to the agent: read the account, preview orders, rebalance to weights, and send previewed orders. Sending requires a token issued after the checks pass.
Can it trade a live account?
No. It works only with an Alpaca paper account and refuses live keys. There is no setting that turns on real trading.
