内容
# tossinvest-mcp
[](https://lobehub.com/mcp/scjang01-tossinvest-mcp)
## 程序概述
`tossinvest-mcp`是一个本地MCP服务器，允许您在MCP支持的应用程序（如OpenAI服务、Claude Desktop、Cursor）中使用Toss证券的开放API（当前价格查询、订单、余额查询等）。
简单来说，注册此程序到MCP客户端后，您可以向AI提出以下请求：
```text
查询三星电子的当前价格。
```
```text
显示我的Toss证券持仓股票。
```
```text
显示待处理订单列表。
```
此程序仅在您的计算机上运行。
## 最重要的注意事项
Toss证券开放API没有沙盒或模拟投资环境。
启用交易功能后，您可以创建、修改和取消实际账户中的实际订单。在首次使用时，请务必先关闭交易功能，仅使用查询功能。
在默认设置中，不会注册订单创建、修改和取消工具。
## 程序功能及特点
即使不启用交易功能，您也可以使用以下功能：
- 查询国内/美国股票当前价格
- 查询买卖报价
- 查询最近成交记录
- 查询蜡烛图表
- 查询涨停/跌停信息
- 查询股票基本信息
- 查询投资注意事项
- 查询汇率
- 查询国内/美国市场交易时间
- 查询账户列表
- 查询持仓股票
- 查询可买入金额
- 查询可卖出数量
- 查询交易手续费
- 查询订单列表
- 查询订单详情
启用交易功能后可使用的工具：
- `toss_create_order`: 创建订单
- `toss_modify_order`: 修改订单
- `toss_cancel_order`: 取消订单
特点：
- 通过`npx tossinvest-mcp`运行，因此单独的程序安装过程很短。
- API密钥和密钥作为环境变量传递。
- OAuth令牌在内部自动颁发，并在过期前60秒自动刷新。
- 需要账户的功能默认使用`accountSeq`为1的账户。
- 如果您有多个账户或想使用其他账户，可以通过设置`TOSSINVEST_ACCOUNT`的值来更改。
- 订单创建、修改和取消功能默认关闭。
- 即使启用订单功能，如果没有`confirmOrderAction: true`的确认值，也不会调用订单API。
- 高级选项`TOSSINVEST_YOLO_TRADING=true`可以跳过`confirmOrderAction`确认，但建议不要使用，因为它可能会降低防止错误交易的保护措施。
重要：`toss_modify_order`不是简单地修改现有订单。Toss证券API以替换原始订单的方式处理修改，并返回新的`orderId`。后续查询订单详情、修改或取消时，请使用新获得的`orderId`。
## 安装方法
请按照以下步骤进行：
### 1. Node.js安装确认
打开终端或PowerShell，输入以下命令：
```bash
node -v
```
如果显示`v20`或以上版本，则可以进入下一步。
如果没有安装Node.js或版本较低，请从https://nodejs.org下载LTS版本，然后重新打开终端进行确认。
### 2. 准备Toss证券开放API密钥
登录Toss证券WTS后，进入开放API设置页面。
在该页面上获取以下值：
- `API密钥`
- `密钥`
这两个值需要放入MCP设置中，请勿与他人共享。
### 3. 注册允许的IP地址
Toss证券开放API仅允许从已注册的IP地址调用。如果未注册，则会出现“IP地址不允许访问”等错误。
首先，确认当前计算机的公网IP地址。可以使用以下命令：
PowerShell（Windows）：
```powershell
(Invoke-WebRequest -UseBasicParsing https://api.ipify.org).Content
```
macOS或Linux终端：
```bash
curl https://api.ipify.org
```
获取的IP地址添加到Toss证券WTS的开放API设置页面的允许IP地址列表中。
大致流程：
1. 登录Toss证券WTS。
2. 进入设置 - 开放API菜单。
3. 找到允许的IP地址管理区域。
4. 添加您刚刚确认的公网IP地址。
### 4. 注册到MCP客户端
在MCP客户端的设置文件或MCP服务器设置页面中添加以下内容：
```json
{
"mcpServers": {
"tossinvest": {
"command": "npx",
"args": ["tossinvest-mcp"],
"env": {
"TOSSINVEST_API_KEY": "获得的API密钥",
"TOSSINVEST_SECRET_KEY": "获得的密钥"
}
}
}
}
```
设置完成后，请完全退出MCP客户端并重新启动。
首次运行时，npm会自动下载`tossinvest-mcp`包。
### 5. 确认账号
一开始不需要设置`TOSSINVEST_ACCOUNT`。此程序默认使用`accountSeq`为1的账户。
但是，如果您有多个账户或想确认账户是否正确，可以查询账户列表。
在MCP客户端中提出以下请求：
```text
查询Toss证券账户列表。
```
在响应中找到`accountSeq`值。如果您想使用其他账户，请在设置中添加或更改以下值：
```json
"TOSSINVEST_ACCOUNT": "1"
```
例如，如果`accountSeq`为2，请这样设置：
```json
"TOSSINVEST_ACCOUNT": "2"
```
如果未设置`TOSSINVEST_ACCOUNT`，则默认为`1`。设置后，在需要账户的功能中，如持仓股票、订单列表、购买金额等，将使用指定的账户。
### 6. 查询功能测试
在MCP客户端中提出以下请求：
```text
查询三星电子的当前价格。
```
```text
显示我的Toss证券持仓股票。
```
```text
查询AAPL最近10笔成交记录。
```
```text
显示待处理订单列表。
```
## 启用交易功能
再次确认，Toss证券开放API没有沙盒。启用交易功能后，可以发出实际订单。
要使用交易功能，请在MCP设置的`env`中添加以下值：
```json
"TOSSINVEST_ENABLE_TRADING": "true"
```
完整示例：
```json
{
"mcpServers": {
"tossinvest": {
"command": "npx",
"args": ["tossinvest-mcp"],
"env": {
"TOSSINVEST_API_KEY": "获得的API密钥",
"TOSSINVEST_SECRET_KEY": "获得的密钥",
"TOSSINVEST_ACCOUNT": "1",
"TOSSINVEST_ENABLE_TRADING": "true"
}
}
}
}
```
即使启用交易功能，订单工具也需要额外的确认值。创建、修改或取消订单时，请求输入中必须有`confirmOrderAction: true`。
### 在请求中设置`confirmOrderAction`为`true`
`confirmOrderAction`不是MCP设置的环境变量。它是调用订单创建、修改或取消工具时必须输入的参数。
例如，实际的订单创建请求可能如下所示：
```json
{
"confirmOrderAction": true,
"symbol": "005930",
"side": "BUY",
"orderType": "LIMIT",
"quantity": "1",
"price": "70000"
}
```
在MCP客户端中请求时，建议明确说明：
```text
在Toss证券中，购买1股三星电子，限价70000韩元。
请确认订单执行并设置confirmOrderAction值为true。
```
修改或取消订单也是如此。
```text
将该订单修改为71000韩元。
请确认订单修改并设置confirmOrderAction值为true。
```
```text
取消该订单。
请确认订单取消并设置confirmOrderAction值为true。
```
根据客户端的不同，可能会在执行订单工具之前显示确认按钮或确认窗口。在这种情况下，订单输入中也必须包含`confirmOrderAction: true`。
### 在没有确认值的情况下执行订单
通常不建议这样做。但是，在自动化环境中，如果难以每次都输入确认值，可以添加以下设置：
```json
"TOSSINVEST_YOLO_TRADING": "true"
```
此选项仅在`TOSSINVEST_ENABLE_TRADING=true`启用时才有意义。如果两者都启用，订单创建、修改和取消工具可以在没有`confirmOrderAction`的情况下调用Toss证券API。
完整示例：
```json
{
"mcpServers": {
"tossinvest": {
"command": "npx",
"args": ["tossinvest-mcp"],
"env": {
"TOSSINVEST_API_KEY": "获得的API密钥",
"TOSSINVEST_SECRET_KEY": "获得的密钥",
"TOSSINVEST_ACCOUNT": "1",
"TOSSINVEST_ENABLE_TRADING": "true",
"TOSSINVEST_YOLO_TRADING": "true"
}
}
}
}
```
此设置可能会增加错误交易的可能性。不建议在初始安装或一般使用期间启用此选项。
## 环境变量说明
| 名称 | 是否必填 | 说明 |
| --- | --- | --- |
| `TOSSINVEST_API_KEY` | 是 | Toss证券开放API页面的API密钥 |
| `TOSSINVEST_SECRET_KEY` | 是 | Toss证券开放API页面的密钥 |
| `TOSSINVEST_ACCOUNT` | 否 | 默认使用的Toss证券`accountSeq`。未设置时默认为`1` |
| `TOSSINVEST_BASE_URL` | 否 | 默认值为`https://openapi.tossinvest.com` |
| `TOSSINVEST_ENABLE_TRADING` | 否 | 设置为`true`后，订单创建、修改和取消工具将被注册 |
| `TOSSINVEST_YOLO_TRADING` | 否 | 设置为`true`后，订单工具在没有`confirmOrderAction`的情况下调用API。不建议使用 |
## 问题解决
### 出现`node`命令找不到的错误
Node.js未安装或未注册到PATH中。请从https://nodejs.org下载LTS版本，然后重新打开终端并重试。
### 出现“IP地址不允许访问”的错误
当前计算机的公网IP地址未注册到Toss证券开放API的允许IP地址列表中。
请确认本文的“安装方法 > 3. 注册允许的IP地址”并注册当前的公网IP地址。网络环境可能会发生变化，如在家、公司、咖啡馆或使用VPN时，公网IP地址可能会改变。
### MCP客户端中工具不可见
请检查设置JSON的语法是否正确，并完全退出MCP客户端后重新启动。如果`TOSSINVEST_API_KEY`和`TOSSINVEST_SECRET_KEY`为空，则服务器不会启动。
### 查询账户信息时报错
持仓股票、订单、购买金额等与账户相关的功能需要`accountSeq`。此程序默认使用`1`。如果查询账户列表的结果显示需要使用其他`accountSeq`，请将`TOSSINVEST_ACCOUNT`更改为该值并重试。
### 订单工具不可见
这是正常的。默认情况下不会注册订单工具。要允许实际交易，请将`TOSSINVEST_ENABLE_TRADING`设置为`true`。
### 已设置`TOSSINVEST_ENABLE_TRADING`为`true`，但仍无法下单
即使订单工具可见，默认设置也需要每个订单请求输入`confirmOrderAction: true`。
请在向AI请求订单时明确说明：
```text
请确认订单执行并设置confirmOrderAction值为true。
```
如果在自动化环境中难以每次都输入此值，可以使用`TOSSINVEST_YOLO_TRADING=true`，但不建议使用此选项，因为它可能会增加错误交易的可能性。
### 修改订单后，使用原始orderId查询的内容异常
Toss证券订单修改会返回新的`orderId`。请使用修改响应中的新`orderId`。
## 开发人员
如果您想直接获取此存储库并进行开发：
```bash
npm install
npm run typecheck
npm test
npm run build
```
如果您想在模拟服务器上测试订单工具流程（无需实际订单）：
```bash
npm run smoke:trading:mock
```
## 免责声明
此程序是一种工具，连接Toss证券开放API以便在MCP中使用。它不提供投资咨询、投资建议、交易推荐或收益保证服务。
使用此程序查询的信息、AI生成的答案或AI建议的订单内容可能不准确、延迟或与用户的意图不符。所有投资决策、订单执行和程序使用的最终责任在于用户。
如果启用交易功能并使用订单创建、修改和取消工具，则实际订单可能会发送到实际账户中。请在订单前直接确认股票、价格、数量、订单类型和账户。
目前，该项目仍在开发中，项目的开发者和分发者不承担因使用此程序而产生的投资损失、订单错误、API故障、数据错误、客户端故障、AI响应错误等责任。
## 许可证
MIT License
Toss证券开放API官方文档：https://developers.tossinvest.com/docs
