Paper Trading MCP

Connect a local AI agent to your KH paper trading account with a standard MCP stdio server. Your client launches a local Node.js process; configure a command and a paper token, without entering a hosted endpoint URL.

The package supports stock orders, standard stock/ETF options, custom spreads, account history, and competition standings. It connects to the hosted paper brokerage, which remains responsible for balances, internal pricing, execution, collateral, and scores. Account tools return stored cash, holdings, cost basis and fills; contract search returns metadata. They do not offer quotes or price previews. The competition tool returns stored standings, including scores. Internet access is required; this is not an offline trading simulator or a real-money brokerage.

Local agent → local MCP process (stdio) → hosted paper brokerage (HTTPS)
                                           ├─ paper account and ledger
                                           ├─ market data and order execution
                                           └─ competition rules and standings

Sign in and manage paper accounts

Requires Node.js 20.19 or newer and npm. Version 0.3.0 adds browser-approved onboarding for an existing KH account. Use the pinned version below, or use source installation for development.

Configure your local MCP client:

{
  "mcpServers": {
    "paper-trading": {
      "command": "npx",
      "args": ["-y", "@hkrds1996/paper-trading-mcp@0.3.2"]
    }
  }
}

1. Ask the agent to call paper_sign_in.

2. Open the returned KH link yourself, sign in to your existing website account, compare the confirmation code, and approve the request. If you sign in in another tab, return to the approval tab and click Check sign-in again. Never approve a request you did not start.

3. Ask the agent to call paper_complete_sign_in. Poll no more than once every five seconds; approval requests expire after ten minutes.

4. The agent can list competitions, create practice accounts, join competitions and trade on your owned paper accounts. Token management is available only if separately approved on the consent screen.

The approved management session lasts for the duration selected during browser approval (default 24 hours, up to the backend-configured maximum), is held only in the local process memory, and needs new sign-in after a process restart. paper_sign_out revokes it. You can also revoke sessions from Paper Trading → MCP access → Signed-in MCP sessions. Revocation and expiry disable session-bound child tokens. Explicitly approved independent agent tokens retain their own lifetime and must be revoked separately. They do not cancel orders already accepted by the brokerage.

This browser approval protocol is specific to the local stdio bridge. It is not an advertised OAuth authorization server for arbitrary remote MCP clients. No login password, browser cookie, device secret, or management bearer token is exposed in tool results. The local bridge generates the management secret, sends only its hash during approval, and authenticates to the backend after approval.

Related MCP server: otto

Tools for onboarding

Account creation reuses an existing result for the same requestId and rejects changed details. Repeated competition joins return the existing entry. Token creation never reissues an old secret: a repeated requestId returns metadata only. If a token response or local write was lost, revoke that token and create another with a new request ID.

paper_create_token saves the one-time child token in a private file under ~/.config/kh-paper-trading/tokens/ (or PAPER_TRADING_CREDENTIAL_DIR). Its tool result contains metadata and the file path, not the secret. Configure another local agent with PAPER_TRADING_TOKEN_FILE. By default these credentials expire with the approving session. For unattended agents, separately approve independent-token creation and call paper_create_token with independent: true and ttlDays (365 days by default, bounded by backend policy). Independent tokens survive session expiry, browser sign-out, and local process restarts when loaded from the saved file. They cannot grant management permissions or issue other tokens. File-based handoff currently targets agents on the same machine.

Public competition creation remains restricted to admin website sessions; this MCP management grant does not delegate admin privileges or expose a competition-creation tool. New KH website registration is not included.

Use an existing account token instead

For a permanently configured agent restricted to one account, add an env object to the server configuration:

"env": { "PAPER_TRADING_TOKEN": "YOUR_PAPER_TRADING_TOKEN" }

Or set PAPER_TRADING_TOKEN_FILE to an absolute private token-file path. Set only one token source. POSIX token files must be owner-only (chmod 600); Windows uses account ACLs. Prefer your client's secret settings when available. A literal token in JSON is stored in that configuration file. Do not commit it. Existing account tokens keep their original restrictions and do not receive the onboarding tools.

Client templates: Claude Desktop, Cursor, VS Code. Merge the entry into your existing configuration. GUI clients need npx on their PATH; Windows clients may require npx.cmd. No backend checkout, Theta Terminal installation, or market-data key is needed on an agent's computer.

Configuration and checks

With an account token already in the environment, npx -y @hkrds1996/paper-trading-mcp@0.3.2 --check checks read-only tool discovery. It does not verify provider entitlement or execute a trade. Without an account token, start normal MCP mode and use the sign-in tools.

See the tool reference for existing stock, option, spread and account-record operations. This release adds onboarding; it does not add live quote or price-preview tools.

What remains controlled by the brokerage

Every participant in a competition receives the same competition-defined starting deposit once. MCP cannot fund or reset an account, transfer balances, edit positions or purchase prices, or set scores. Account-token write tools place and cancel paper orders. Browser-approved management sessions can also provision accounts, join competitions and manage delegated tokens. Limits constrain acceptable prices; the server determines actual fills from market data.

New portfolio-margin-v2 accounts support custom orders of up to 16 legs, including long/short standard options and spreads, subject to collateral and account rules. Existing cash-long-v1 accounts retain their original restrictions. This package exposes the same rules as the dashboard; it does not remove backend limits. Index/futures options, adjusted contracts, and physical exercise/assignment are not supported.

The agent's tool arguments and the paper token are sent to the configured backend over HTTPS by default; stored account records, order outcomes, and option contract metadata go back to your agent client. The package does not store a second ledger or require any brokerage credentials locally. Simulated execution depends on the provider configuration of the backend you connect to. No quote or order-price-preview tools are exposed. Owner dashboards read separately persisted valuation snapshots and label their source and age; refreshing the dashboard does not request current prices.

Troubleshooting

The backend shares request budgets across your tokens, accounts, REST calls and MCP calls. Orders, contract searches and account reads have separate budgets; cancellation has its own allowance. Larger spreads and contract pages consume more budget. When throttled, tool errors include retryAfterSeconds when the server supplies it. Wait that long and reduce parallel calls. The local bridge never automatically retries an order.

Install from source

This remains available independently of npm publication. Git is required.

git clone https://github.com/hkrds1996/paper-trading-mcp.git
cd paper-trading-mcp
npm ci
node bin/paper-trading-mcp.js --version

Use command: "node" and args: ["/absolute/path/to/paper-trading-mcp/bin/paper-trading-mcp.js"] in your MCP configuration, retaining the same token environment setting. Keep the checkout in place. This project needs no backend checkout or build step.

Development

npm ci
npm test

This project implements the local transport and forwards the allowed paper tools to the backend. Changes to balances, execution, or competition accounting belong in the backend. See architecture and operational behavior.