Content
# Oh-My-Stock-MCP
A local MCP server that reads assets, accounts, holdings, and transactions from Korean securities company websites.
[](https://github.com/rootnix/Oh-My-Stock-MCP/actions/workflows/ci.yml)
[](https://github.com/rootnix/Oh-My-Stock-MCP/actions/workflows/docker-publish.yml)
[](https://ghcr.io/rootnix/oh-my-stock-mcp)
[](./LICENSE)
> A server for checking Korean stock assets with MCP tools
- Supported brokers: `samsungpop`, `shinhansec`, `miraeasset`, `nhsec`, `korsec`, `kiwoom`
- Execution methods: Node.js / Docker / MCP stdio
- Common interface: normalized summary / accounts / holdings / transactions
## Status Notation
- ✅ Supported
- ⚠️ Partially supported / Limited
- ❌ Not supported
## Easiest Way to Get Started
```bash
docker pull ghcr.io/rootnix/oh-my-stock-mcp:latest
cp .env.example .env
mkdir -p .data
docker run -i --rm \
--env-file .env \
-v "$(pwd)/.data:/app/.data" \
ghcr.io/rootnix/oh-my-stock-mcp:latest
```
## Broker Coverage
> Last verification: **2026-04-23 (KST)**
### Summary
| Broker | Broker ID | Login | Assets | Accounts | Holdings | Transactions | Performance/Analysis | Notes |
| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | --- |
| Samsung Securities | `samsungpop` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Most complete |
| Shinhan Investment Securities | `shinhansec` | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | Almost as good as Samsung Securities |
| Mirae Asset Securities | `miraeasset` | ✅ | ✅ | ✅ | ✅ | ❌ | ⚠️ | Currently asset-centric |
| NH Investment Securities | `nhsec` | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | Widely connected to detailed tabs |
| Korea Investment Securities (ID Login) | `korsec` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | Browser asset/ balance-centric |
| Korea Investment Securities OpenAPI | `korsec` | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | App Key/Secret-based, includes transactions and period profits |
| Kiwoom Securities OpenAPI | `kiwoom` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | REST OpenAPI (app key/secret)-based |
### Detailed Matrix
| Feature | Samsung Securities | Shinhan Investment Securities | Mirae Asset Securities | NH Investment Securities | Korea Investment Securities ID | Korea Investment Securities OpenAPI | Kiwoom Securities OpenAPI |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| Total Asset Summary | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Account List | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Account Details | ✅ | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | ⚠️ |
| Domestic Stock Holdings | ⚠️* | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
| Foreign Stock Holdings | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ⚠️ |
| Fund/Financial Product Holdings | ⚠️ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ⚠️ |
| Pension/Retirement Pension | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| Cash/Cash Equivalent Assets | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Foreign Currency Balance | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ⚠️ |
| Comprehensive Transaction History | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ |
| Deposit/Withdrawal History | ✅ | ✅ | ❌ | ✅ | ❌ | ⚠️** | ✅ |
| Stock Transaction History | ✅ | ✅ | ❌ | ⚠️ | ❌ | ⚠️** | ✅ |
| Fund Transaction History | ⚠️ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| Wrap/RP/MMW Transactions | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| Portfolio Analysis | ✅ | ✅ | ⚠️ | ❌ | ❌ | ❌ | ⚠️ |
| Daily/Monthly Performance History | ✅ | ⚠️ | ❌ | ❌ | ❌ | ⚠️** | ⚠️ |
| Deep Snapshot | ✅ | ✅ | ✅** | ✅ | ✅ | ✅ | ✅ |
\* Samsung Securities domestic stock parser is implemented but verification range is limited to real accounts.
\** Korea Investment Securities OpenAPI's deposit/withdrawal/stock transaction/performance history has limited verification range. Mirae Asset's `Deep Snapshot` is currently asset-centric.
## Recent Changes
| Date | Changes |
| --- | --- |
| 2026-04-23 | Added Mirae Asset asset/holdings support, expanded NH structured accounts/holdings/transactions and detailed balance/special asset tabs, added Korea Investment Securities browser asset status + OpenAPI (accounts/balance/transactions/performance) support, added Kiwoom OpenAPI asset/accounts/holdings/transactions/period performance support |
| 2026-04-22 | Expanded Shinhan Investment Securities asset/transactions/financial product range, added normalized tool |
| 2026-04-21 | Initial release of Samsung Securities-based MCP server |
## Key Features
- Provides an integrated tool for checking multiple brokers at once
- Asset snapshot query
- Account list/account details query
- Holdings/stocks/funds/pension/foreign assets query
- Transaction history/deposit/withdrawal/some financial product transaction history query
- Broker-common normalized response
## Precautions
- Never share files containing authentication information, such as `.env` and `.data/sessions`.
- Some features may break due to changes in the broker's website structure.
- Check each broker's terms of use and security policy before use.
## Local Execution
```bash
npm install
npm run build
npm start
```
Development mode:
```bash
npm run dev
```
## Account Settings
```bash
cp .env.example .env
```
### Samsung Securities
Recommended settings:
```dotenv
SAMSUNGPOP_AUTH_MODE=manual_session
```
```bash
npm run auth:samsungpop
```
Using auto-login:
```dotenv
SAMSUNGPOP_AUTH_MODE=credentials
SAMSUNGPOP_USER_ID=...
SAMSUNGPOP_USER_PASSWORD=...
SAMSUNGPOP_ACCOUNT_PASSWORD=1234
SAMSUNGPOP_ACCOUNT_NUMBER_HINT=12345678
```
### Shinhan Investment Securities
```dotenv
SHINHANSEC_AUTH_MODE=credentials
SHINHANSEC_USER_ID=...
SHINHANSEC_USER_PASSWORD=...
SHINHANSEC_ACCOUNT_PASSWORD=1234
```
Manual session storage:
```bash
npm run auth:shinhansec
```
### Mirae Asset Securities
```dotenv
MIRAEASSET_AUTH_MODE=credentials
MIRAEASSET_USER_ID=...
MIRAEASSET_USER_PASSWORD=...
```
Manual session storage:
```bash
npm run auth:miraeasset
```
> Currently, Mirae Asset is supported mainly for assets and holdings. Sensitive pages like transactions require additional authentication.
> `get_all_transactions` integrated query excludes Mirae Asset Securities.
### NH Investment Securities
```dotenv
NHSEC_AUTH_MODE=credentials
NHSEC_USER_ID=...
NHSEC_USER_PASSWORD=...
```
Manual session storage:
```bash
npm run auth:nhsec
```
> Currently, NH Investment Securities supports My Assets, comprehensive balance, transaction history, deposit/withdrawal, foreign securities, trust, Wrap, RP/MMW, and detailed balance tabs.
### Korea Investment Securities
```dotenv
KORSEC_AUTH_MODE=api
KORSEC_APP_KEY=...
KORSEC_SECRET_KEY=...
KORSEC_ACCOUNT_NUMBER=12345678
KORSEC_ACCOUNT_PRODUCT_CODE=01
```
Browser (ID login) mode example:
```dotenv
KORSEC_AUTH_MODE=credentials
KORSEC_USER_ID=...
KORSEC_USER_PASSWORD=...
```
Session/token settings:
```bash
npm run auth:korsec
```
> In browser (ID login) mode, it supports asset status (summary), asset status (comprehensive balance evaluation), and stock/fund/CMA/Wrap/bond/RP/IMA tab balance summaries.
> In OpenAPI mode, it supports accounts/domestic and foreign balance/transaction history/period profit/loss/foreign balance, and is included in `get_all_transactions` integrated query.
> OpenAPI works most stably with official KIS Developers App Key/App Secret and account number (8 digits) + product code (2 digits).
### Kiwoom Securities OpenAPI
```dotenv
KIWOOM_AUTH_MODE=api
KIWOOM_APP_KEY=...
KIWOOM_SECRET_KEY=...
```
Token cache check:
```bash
npm run auth:kiwoom
```
> Kiwoom Securities works with REST OpenAPI, not browser sessions.
> Currently, it supports account number, deposit/withdrawable amount, holdings evaluation, transaction history, daily balance profit/loss, and period profit/loss.
> Kiwoom Securities API key issuance/usage guide: https://openapi.kiwoom.com/main/home
## Docker Execution
### Using Public Image
```bash
docker pull ghcr.io/rootnix/oh-my-stock-mcp:latest
docker run -i --rm \
--env-file .env \
-v "$(pwd)/.data:/app/.data" \
ghcr.io/rootnix/oh-my-stock-mcp:latest
```
### Building from Source
```bash
docker build -t oh-my-stock-mcp .
docker run -i --rm \
--env-file .env \
-v "$(pwd)/.data:/app/.data" \
oh-my-stock-mcp
```
## MCP Client Settings Example
See [`docs/MCP_CLIENTS.md`](docs/MCP_CLIENTS.md) for detailed examples.
Node execution example:
```json
{
"oh-my-stock-mcp": {
"command": "node",
"args": ["/absolute/path/to/Oh-My-Stock-MCP/dist/index.js"]
}
}
```
Docker execution example:
```json
{
"oh-my-stock-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--env-file",
"/absolute/path/to/Oh-My-Stock-MCP/.env",
"-v",
"/absolute/path/to/Oh-My-Stock-MCP/.data:/app/.data",
"ghcr.io/rootnix/oh-my-stock-mcp:latest"
]
}
}
```
## Common Normalized Tools
- `get_all_assets`
- `get_all_accounts`
- `get_all_holdings`
- `get_all_transactions`
- `get_portfolio_overview`
- `get_normalized_asset_summary`
- `get_normalized_accounts`
- `get_normalized_holdings`
- `get_normalized_transactions`
Example of main fields:
- Asset summary: `totalAssetRaw`, `totalAssetValue`, `profitLossRaw`, `profitLossValue`, `returnRateRaw`, `returnRateValue`
- Holdings: `category`, `productName`, `productCode`, `purchaseAmountValue`, `evaluationAmountValue`
- Transactions: `sourceType`, `kind`, `direction`, `assetCategory`
Normalized asset semantics are fixed based on `docs/normalized-asset-semantics.md`.
- `evaluationAmountValue`: **KRW-denominated evaluation amount sum of deduplicated normalized holdings**
- `assetComposition`: **interpreted based on holdings aggregation**
- `brokerReportedEvaluationAmountValue`: Broker-reported evaluation amount
- `totalAssetValue = evaluationAmountValue + nonHoldingAssetAmountValue`
- `cashBalanceValue`, `cashEquivalentBalanceValue`, `foreignCashBalanceValue`, `otherNonHoldingAssetValue` explain non-holding asset
Aggregate tools return broker status together:
- `successBrokerIds`
- `failedBrokerIds`
- `skippedBrokerIds` (`get_all_transactions` skips some brokers like Mirae Asset Securities, Korea Investment Securities browser mode)
- `get_portfolio_overview` provides a top-level portfolio summary combining assets/accounts/holdings/recent transactions.
## Provided Tools
### Common
- `list_brokers`
- `get_broker_auth_status`
- `get_asset_snapshot`
- `get_all_assets`
- `get_all_accounts`
- `get_all_holdings`
- `get_all_transactions`
- `get_portfolio_overview`
- `get_normalized_asset_summary`
- `get_normalized_accounts`
- `get_normalized_holdings`
- `get_normalized_transactions`
### Samsung Securities
- `setup_samsungpop_session`
- `get_samsungpop_investment_performance`
- `get_samsungpop_portfolio_analysis`
- `get_samsungpop_general_balance`
- `get_samsungpop_daily_performance_history`
- `get_samsungpop_monthly_performance_history`
- `get_samsungpop_balance_history`
- `get_samsungpop_overseas_balance`
- `get_samsungpop_accounts`
- `get_samsungpop_account_details`
- `get_samsungpop_holdings`
- `get_samsungpop_foreign_holdings`
- `get_samsungpop_retirement_holdings`
- `get_samsungpop_transactions`
- `get_samsungpop_deep_snapshot`
### Shinhan Investment Securities
- `setup_shinhansec_session`
- `get_shinhansec_asset_analysis`
- `get_shinhansec_investment_performance`
- `get_shinhansec_portfolio_analysis`
- `get_shinhansec_general_balance`
- `get_shinhansec_cma_balance`
- `get_shinhansec_accounts`
- `get_shinhansec_account_details`
- `get_shinhansec_stock_holdings`
- `get_shinhansec_holdings`
- `get_shinhansec_fund_holdings`
- `get_shinhansec_foreign_holdings`
- `get_shinhansec_retirement_holdings`
- `get_shinhansec_financial_products`
- `get_shinhansec_overseas_balance`
- `get_shinhansec_foreign_assets`
- `get_shinhansec_transactions`
- `get_shinhansec_stock_transactions`
- `get_shinhansec_financial_product_transactions`
- `get_shinhansec_check_card_transactions`
- `get_shinhansec_financial_income_statement`
- `get_shinhansec_passbook_transactions`
- `get_shinhansec_cash_transactions`
- `get_shinhansec_deep_snapshot`
### Mirae Asset Securities
- `setup_miraeasset_session`
- `get_miraeasset_accounts`
- `get_miraeasset_product_assets`
- `get_miraeasset_transactions`
- `get_miraeasset_investment_return`
- `get_miraeasset_deep_snapshot`
### NH Investment Securities
- `setup_nhsec_session`
- `get_nhsec_accounts`
- `get_nhsec_balance_details`
- `get_nhsec_holdings`
- `get_nhsec_balance_category`
- `get_nhsec_transactions_structured`
- `get_nhsec_transaction_category`
- `get_nhsec_cash_transactions`
- `get_nhsec_foreign_assets`
- `get_nhsec_special_assets`
- `get_nhsec_my_asset`
- `get_nhsec_general_balance`
- `get_nhsec_total_transactions`
- `get_nhsec_deposit_withdrawals`
- `get_nhsec_foreign_balance`
- `get_nhsec_foreign_transactions`
- `get_nhsec_deep_snapshot`
### Korea Investment Securities
- `setup_korsec_session`
- `get_korsec_asset_summary`
- `get_korsec_general_balance`
- `get_korsec_balance_category`
- `get_korsec_product_balances`
- `get_korsec_accounts`
- `get_korsec_holdings`
- `get_korsec_transactions`
- `get_korsec_performance`
- `get_korsec_overseas_balance`
- `get_korsec_deep_snapshot`
### Kiwoom Securities OpenAPI
- `get_kiwoom_asset_summary`
- `get_kiwoom_accounts`
- `get_kiwoom_holdings`
- `get_kiwoom_transactions`
- `get_kiwoom_daily_balance_return`
- `get_kiwoom_period_performance`
- `get_kiwoom_deep_snapshot`
## Add the following securities
1. Write `src/brokers/<broker-id>/adapter.ts`
2. Connect to `src/config.ts`, `src/brokers/registry.ts`
3. Add broker-specific tools to `src/index.ts` if necessary
4. Add normalized mapper to `src/lib/normalize.ts`
## License
MIT
