# Toss Invest MCP

A personal [MCP](https://modelcontextprotocol.io) server for the
[Toss Securities Open API](https://developers.tossinvest.com/docs). It lets any MCP client read
market data and your account, and (optionally) place real-money orders.

Built with [FastMCP](https://gofastmcp.com); runs locally over stdio.

## Setup

1. **Add credentials** — create `.env` in the project root with keys from
   Toss Securities WTS (Settings → Open API):

   ```dotenv
   API_KEY="tsck_live_..."      # client_id
   SECRET_KEY="tssk_live_..."   # client_secret
   # TOSS_ACCOUNT_SEQ=          # optional: default account
   # TOSS_ENABLE_TRADING=true   # optional: allow placing orders
   ```

2. **Install** — `uv sync`

3. **Connect your MCP client** — point any MCP client at the server using this command:

   ```bash
   uv run --directory /path/to/toss-invest-mcp toss-invest-mcp
   ```

   Or in your client's JSON config:

   ```json
   {
     "mcpServers": {
       "toss-invest": {
         "command": "uv",
         "args": ["run", "--directory", "/path/to/toss-invest-mcp", "toss-invest-mcp"]
       }
     }
   }
   ```

## Tools

**Market data:** `get_prices`, `get_orderbook`, `get_trades`, `get_candles`, `get_price_limits`,
`get_stocks`, `get_stock_warnings`, `get_exchange_rate`, `get_kr_market_calendar`,
`get_us_market_calendar`

**Account:** `get_accounts`, `get_holdings`, `get_buying_power`, `get_sellable_quantity`,
`get_commissions`, `get_orders`, `get_order`

**Trading** (only when `TOSS_ENABLE_TRADING=true`): `create_order`, `modify_order`, `cancel_order`

Account tools take an `account_seq` — call `get_accounts` to find yours, or set
`TOSS_ACCOUNT_SEQ` in `.env`.

## Safety

- Trading tools place **real-money** orders and are **off by default** — they only work with
  `TOSS_ENABLE_TRADING=true`.
- Orders ≥ 100M KRW require `confirm_high_value_order=true`.
- Credentials stay in your local `.env` (git-ignored); nothing is hosted.