KIS_MCP_Server

This MCP server exposes a set of APIs that wrap the Korea Investment & Securities (KIS) REST APIs for domestic and overseas stock trading. It supports real-time price lookups, order placement, balance inquiries, and order history, along with overseas trading capabilities across multiple markets. The server is designed with asynchronous handling to deliver fast responses and provides structured MCP endpoints for domestic stock trading, overseas stock trading, and price inquiries. To use it, run the MCP server using the uv tool (as shown in the installation snippet) and interact with the exposed functions through the MCP client or IDE integrations that understand the MCP format. Typical workflows include establishing your API keys via environment variables, then calling inquery_stock_price, order_stock, inquery_balance, and the overseas equivalents as documented in the Functions section.

Prerequisites:

• Python 3.13+ installed on your system
• uv packaging tool installed (pip install uv)
• Access to a compatible MCP runtime or environment

Step-by-step installation:

1. Install the uv tool if not already installed:

pip install uv

2. Create and activate a Python virtual environment (optional but recommended):

uv venv
# Linux/macOS
source .venv/bin/activate
# Windows
.\venv\Scripts\activate

3. Install the MCP server in editable mode (adjust path as needed):

uv pip install -e .

4. Run MCP server with environment variables for KIS credentials (example):

mcp install server.py \
  -v KIS_APP_KEY={KIS_APP_KEY} \
  -v KIS_APP_SECRET={KIS_APP_SECRET} \
  -v KIS_ACCOUNT_TYPE={KIS_ACCOUNT_TYPE} \
  -v KIS_CANO={KIS_CANO}

5. Alternatively, configure the server via mcp-config.json (see next section) and run using MCP-compatible tooling.

Tips and considerations:

• Store your KIS credentials securely; do not commit them to version control.
• The MCP server supports both domestic and overseas stock operations. Ensure your account type and market permissions align with the actions you perform.
• When testing, start with virtual accounts (KIS_ACCOUNT_TYPE=VIRTUAL) and mock data where possible.
• If you encounter environment-variable issues, verify the runtime environment is loading the .env or exported variables before starting the server.
• Review trading hours for domestic and overseas markets to avoid time-based errors during order placement.
• The configuration example uses uv as the runtime; adapt the command and environment as needed for your deployment (e.g., containerized or scheduler-based setups).