Content
# 📊 kiwoom-private-mcp-server
A personal Model Context Protocol (MCP) server that utilizes the Kiwoom Securities REST API to retrieve stock account information and evaluate the status of held stocks.
It can be integrated with LLM clients such as Claude Desktop and Cursor, allowing AI to directly assess investment asset status and perform sector suitability analysis.
## 🚀 Key Features (MCP Tools)
* **`get_accounts`**: Retrieves a list of Kiwoom Securities accounts defined by the user and target sector information for each account.
* **`get_account_balance`**: Queries the total evaluated assets of a specific account, evaluation amounts of individual held stocks, proportions, average purchase prices, and profit rates. (Supports actual server API connection and mock query)
## 🛠️ Requirements and Technical Stack
* **Python**: `3.10` or higher
* **Dependency Tools**:
* [**uv**](https://github.com/astral-sh/uv): A high-speed Python package/project manager developed in Rust
* `mcp`: Anthropic Model Context Protocol SDK
* `requests`: API HTTP communication library
* `python-dotenv`: Local environment variable (`.env`) loading library
## 📦 Installation and Local Setup
### 1. Install `uv` Tool (Rust-based High-Speed Package Manager)
Run the following command in the terminal (PowerShell or bash) to install `uv`.
* **Windows (PowerShell)**:
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
* **macOS / Linux**:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
* **Existing pip usage**:
```bash
pip install uv
```
### 2. Create Virtual Environment and Install Packages
Use the following command in the project root directory to synchronize dependencies at high speed.
```bash
# Create virtual environment (.venv)
uv venv
# Install packages defined in pyproject.toml and build local project
uv pip install -e .
```
### 3. Configure Environment Settings Files
Copy setting template files to create actual setting files for local security and account information mapping. (These files are registered in `.gitignore` and excluded from Git management.)
1. **Create Environment Variable File (`.env`)**:
Copy `.env.example` to create `.env` and enter the AppKey and SecretKey required for Kiwoom API authentication.
```bash
cp .env.example .env
```
* Setting `KIWOOM_USE_MOCK=false` retrieves real-time information from the Kiwoom API server. Setting `true` returns built-in mock portfolio information.
2. **Create Account Mapping Configuration File (`accounts_config.json`)**:
Copy `accounts_config.json.example` to create `accounts_config.json` and enter the used account numbers and target investment sector names for each account.
```bash
cp accounts_config.json.example accounts_config.json
```
## 💻 Execution and Integration Guide
### 1. Local Standalone Test
Use `uv` to directly run the FastMCP server from the command line to verify that it starts without errors.
```bash
uv run mcp_server.py
```
* If the server starts normally, the `mcp.server.fastmcp` engine operates and enters input/output standby mode.
### 2. Claude Desktop Integration Settings
Add the following configuration to the setting file (`config.json`) so that Claude Desktop can recognize this server.
* **Setting File Location**: `C:\Users\<username>\AppData\Roaming\EasyConnect\config.json` or `%APPDATA%\Claude\claude_desktop_config.json`
* **Added Setting Content (Windows example)**:
```json
{
"mcpServers": {
"kiwoom-private-mcp-server": {
"command": "uv",
"args": [
"run",
"--directory",
"c:/Users/moony/home_document/kiwoom-rest-api/kiwoom-private-mcp-server",
"mcp_server.py"
]
}
}
}
```
### 3. Cursor IDE Integration Settings
1. Go to Cursor settings (`Settings` -> `Features` -> `MCP`).
2. Click the `+ Add New MCP Server` button.
3. Enter the following:
* **Name**: `kiwoom-private-mcp-server`
* **Type**: `command`
* **Command**: `uv run --directory c:/Users/moony/home_document/kiwoom-rest-api/kiwoom-private-mcp-server mcp_server.py`
## 🔒 Security Precautions
* This project handles personal investment accounts and sensitive API authentication information (`AppKey`, `SecretKey`).
* Be extremely cautious not to commit/push **`.env`** files and **`accounts_config.json`** files to a public GitHub repository. (Basically, `.gitignore` protects against this.)
