Provides tools to fetch stock market data (market overview, gainers, quotes, news, fundamentals, recommendations) from Naver Finance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kookmin-stock get the market overview for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Kookmin University Assignment Β· "Boosting Impact with Hermes + Custom MCP Server"
We prove how work quality changes through 3 experiments by attaching a custom MCP server to the domestic stock recommendation Hermes agent created in the previous assignment.
Output | Path | Description |
MCP Server (Normal) |
| FastMCP stdio, 6 tools |
MCP Server (Broken Version) |
| Incorrect description / Timeout / Empty response |
30-second Demo |
| Sequence output for recording |
Experiment β‘ Result Comparison |
| NO MCP / GOOD / BROKEN comparison |
Experiment β’ Pattern Comparison |
| Single / Planner+Executor / Parallel |
Presentation Slides (spec) |
| Paste into another AI to generate PPT |
Result Outputs |
| Auto-generated tables, CSVs, logs |
Related MCP server: pykrx-mcp
Python 3.10+ (Test environment 3.13).
python -m venv .venv
source .venv/bin/activate
pip install -e .# 1) MCP μλ² κ²μ¦ (μλ²λ stdioλΌ νΈμ€νΈκ° λΆμ΄μΌ μλ―Έ μμ β Ctrl+Cλ‘ μ’
λ£)
python -m mcp_stock.server
# 2) 30μ΄ λμ λ°λͺ¨ (μ€μ λ‘ λλ €μ λ
Ήν)
python -m experiments.exp1_demo
# λλ ./demo/record_demo.sh
# 3) μ€ν β‘ μ±κ³΅/μ€ν¨ λΉκ΅ β results/exp2_* μλ μμ±
python -m experiments.exp2_quality
# 4) μ€ν β’ Orchestration ν ν° λΉκ΅ β results/exp3_* μλ μμ±
python -m experiments.exp3_orchestrationActions by timecode are organized in demo/demo_script.md.
The simplest path:
./demo/record_demo.sh # QuickTime/Cmd+Shift+5 λ‘ νλ©΄ λ
Ήννλ©΄μ μ€ν
./demo/record_demo.sh --asciinema # ν
μ€νΈ μΊ‘μ² (asciinema νμ)Tool | Input | Output |
| 'today' / YYYY-MM-DD |
|
| KOSPI/KOSDAQ, 1..50 | Top N stocks |
| Code or Korean name | close / changePct / volume / per / pbr |
| Keyword or stock name | Headline + |
| Code or Korean name | per / pbr / eps / bps / roe |
| KOSPI/KOSDAQ | scoreBreakdown + rationale |
Data: Naver Finance crawling single source (src/mcp_stock/sources/naver.py). Free, no key required.
Indices: polling.finance.naver.com/api/realtime/domestic/index/{KOSPI|KOSDAQ} JSON
Top Gainers: finance.naver.com/sise/sise_rise.naver?sosok={0|1} HTML
Stock Details / PERΒ·EPSΒ·PBRΒ·Dividends: finance.naver.com/item/main.naver?code=... (Stable emphasis tags like id="_per")
News by Stock: finance.naver.com/item/news_news.naver?code=...
Safe operation with automatic fallback snapshots during market holidays or Naver page changes.
exp2_quality.py runs the same user questions across three environments and auto-generates tables and failure logs.
(a) NO MCP β 0 tools. LLM answers only with training data β Hallucinations, lack of evidence.
(b) GOOD MCP β Normal custom server. 12 tool calls, cites 4 positive keywords.
(c) BROKEN MCP β As defined in server_broken.py:
get_top_gainers description incorrectly written as "Top losers" β Model misselection
get_recent_news triggers TimeoutError after time.sleep(5)
get_fundamentals returns an empty dict
Results:
results/exp2_quality_table.md β Comparison table
results/exp2_failure_logs.md β Failed call traces + response body
results/exp2_summary.json β Original statistics
Pattern | Description | Token Characteristics | Response Time Characteristics |
Single | Accumulate tool results in one loop | Input tokens ββ | Slowest |
Planner + Executor | Planner creates sequence, executor summarizes results | Input tokens β | Medium |
Parallel sub-agents | KOSPI / KOSDAQ / NEWS sub-agents run simultaneously | Input tokens ββ | Fastest |
Results:
results/exp3_benchmark.csv β Wide CSV for bar charts
results/exp3_pattern_table.md β Table + Retrospective
results/exp3_summary.json β Full trace per pattern
This repository is designed to produce tokens and traces via deterministic simulation even without LLM API keys. To attach to actual Hermes / Claude Desktop / Cursor:
Simply fill in _callHermes() in src/experiments/runner/hermes_runner.py.
# TODO(user): replace this body with the real Hermes call.
import httpx
response = httpx.post(self.endpoint, headers=..., json=...)
return response.json()After setting environment variables HERMES_ENDPOINT, HERMES_API_KEY,
replace the AgentRunner instance with HermesRunner().
Add to Claude Desktop's claude_desktop_config.json or Cursor MCP settings:
{
"mcpServers": {
"kookmin-stock": {
"command": "python",
"args": ["-m", "mcp_stock.server"],
"cwd": "/path/to/Kookmin-University-MCP",
"env": { "PYTHONPATH": "/path/to/Kookmin-University-MCP/src" }
}
}
}Paste slides/slides.md directly into another AI. Example prompt:
The following markdown is a 12-slide spec for a 5-minute presentation. Please create PowerPoint slides based on the
# Slide Nheaders. Represent### Visualblocks as mermaid diagrams or tables if possible, and put### Speaker Notesinto the slide notes area.
Update results with python -m experiments.exp2_quality && python -m experiments.exp3_orchestration
Record 30-second demo with ./demo/record_demo.sh β demo/demo.mov
GitHub push (Record repository URL in README and slide 6)
Send GitHub URL + slides + demo video to kts123@kookmin.ac.kr (Deadline 5/14 23:59:59)
.
βββ README.md
βββ pyproject.toml / requirements.txt
βββ demo/
β βββ demo_script.md
β βββ record_demo.sh
βββ results/ # μλ μμ±
βββ slides/slides.md
βββ src/
βββ mcp_stock/
β βββ server.py
β βββ server_broken.py
β βββ data/ticker_map.py
β βββ sources/naver.py # λ€μ΄λ² κΈμ΅ ν¬λ‘€λ¬ (λ¨μΌ λ°μ΄ν° μμ€)
β βββ tools/{market, quote, news, fundamentals, recommend}.py
βββ experiments/
β βββ exp1_demo.py
β βββ exp2_quality.py
β βββ exp3_orchestration.py
β βββ runner/{agent_base, mock_runner, hermes_runner}.py
βββ utils/{logger, token_counter}.pySymptom | Cause | Response |
| Stock not on Naver page or structure changed | Uses automatic fallback snapshot β operates normally |
| Network offline | All tools operate safely with fallback snapshots |
Korean characters broken | Terminal font | D2 Coding / Pretendard / SF Mono recommended |
Call on holiday/weekend | Not a business day | Polling API returns the last closing price as is |
Return PER, PBR, EPS, BPS, ROE and dividend yield for a ticker.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior, but it only lists outputs. It omits details like data source, update frequency, error handling, or whether values are real-time. It essentially repeats what the name suggests without added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently conveys the tool's purpose. No extraneous information is included, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and no output schema, the description is adequate but minimal. It lists return metrics but does not expand on acronyms (e.g., PER = Price-to-Earnings Ratio) or provide any usage context. It is acceptable for a simple tool but lacks depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it adds no meaning beyond the parameter name 'ticker'. It does not specify format, example values, or domain constraints, leaving the agent with minimal guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns specific fundamental metrics (PER, PBR, EPS, BPS, ROE, dividend yield) for a given ticker. It uses a specific verb 'Return' and resource 'fundamentals', and the listed metrics distinguish it from sibling tools like get_stock_quote or get_market_overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for different scenarios, leaving the agent to infer context from name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return KOSPI and KOSDAQ index close, daily change percent, and trading value.
Args: date: 'today' or YYYY-MM-DD. Non-business days fall back to the most recent trading day automatically. Returns: {asOf, kospi:{close, changePct, tradingValueKrw}, kosdaq:{...}, source}
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | today |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return fields and date fallback; does not mention side effects but is a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with clear Args/Returns sections. Every sentence adds value; no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description details return structure (nested objects for kospi/kosdaq). Could mention read-only nature but overall adequate for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with zero schema description coverage. Description fully explains its format and fallback behavior, adding essential meaning beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns KOSPI and KOSDAQ index close, daily change percent, and trading value. Distinguishes from sibling tools like get_stock_quote (individual stocks) and get_top_gainers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies acceptable date formats ('today' or YYYY-MM-DD) and fallback behavior for non-business days. Implicitly guides when to use but lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return recent Naver finance news headlines about a ticker or keyword.
Each item carries a positivityScore (sum of catalyst-keyword matches
minus negative-keyword matches) plus the matched keywords.
Args: query: ticker code, Korean stock name, or free-text keyword. top_n: 1..20.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_n | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the positivityScore calculation and that results include matched keywords, offering some behavioral insight. However, it lacks disclosure on whether it's read-only, rate limits, error handling, or other side effects. No annotations to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences plus arg list), front-loaded with the purpose, and includes structured arg descriptions. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers purpose, parameters, and key behavioral detail (positivityScore). It could mention limitations like article count or recency but remains fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by detailing that query accepts ticker codes, Korean stock names, or free-text, and that top_n ranges from 1 to 20. This adds significant meaning beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns recent Naver finance news headlines about a given query. It specifies a unique function not overlapping with siblings like get_fundamentals or get_stock_quote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for news retrieval but does not explicitly differentiate from siblings or provide when-to-use/when-not-to-use guidance. No mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the most recent close, change percent, volume, PER and PBR for a ticker.
Args: ticker: 6-digit code (e.g. '005930') or Korean name (e.g. 'μΌμ±μ μ').
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must convey behavioral traits. It mentions 'most recent' data but does not specify real-time vs delayed, caching, authentication requirements, or other side effects. This is minimal disclosure for a data retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences and a bullet point to convey purpose and parameter details. Every word is necessary, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description adequately covers what data is returned and how to input the ticker. It could mention data source or latency, but overall it is sufficiently complete given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the schema by specifying the ticker parameter can be a 6-digit code or Korean name, including examples. Since schema description coverage is 0%, this is critical and well-done.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns specific stock data (close, change percent, volume, PER, PBR) for a ticker. It distinguishes from siblings implicitly by the data fields, but no explicit differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to specify the ticker but gives no guidance on when to use this tool versus alternatives like get_fundamentals or get_market_overview. No when-not-to-use or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the top N stocks ranked by daily change percent (descending).
Args: market: 'KOSPI' or 'KOSDAQ'. top_n: 1..50. Returns: List of {ticker, name, changePct, close, asOf}.
| Name | Required | Description | Default |
|---|---|---|---|
| market | No | KOSPI | |
| top_n | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states the output is a list of objects with specific fields, but does not mention if the tool is read-only, any authentication requirements, rate limits, or edge cases (e.g., empty list on holidays). The description is factual but lacks depth on behavioral aspects beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a clear docstring format with a one-line purpose followed by Args and Returns. Every sentence adds value, and the structure is easy to parse. No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters with defaults) and the presence of an output schema (implied by context signals), the description is largely complete. It explains parameters, return format, and purpose. However, it could mention the ordering direction (descending) is already clear from the name, but no major gaps. A small addition like 'daily change percent' clarification is fine.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning: market is 'KOSPI' or 'KOSDAQ' (though schema has enum), and top_n range 1..50, which goes beyond the schema's default-only definition. This provides helpful context for parameter use, though the default values are already clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns top N stocks ranked by daily change percent descending. The verb 'Return' and resource 'top N stocks' are specific. Compared to siblings like get_fundamentals or get_stock_quote, this tool's purpose is distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys what the tool does but does not explicitly specify when to use it (e.g., 'for identifying top gainers') or when to avoid it (e.g., 'use get_stock_quote for individual stock details'). No alternatives or exclusions are mentioned, leaving the agent to infer usage from the tool's name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Composite buy-recommendation tool.
Combines top gainers + per-ticker quote, news positivity, and fundamentals
into a ranked list. Each entry includes a transparent scoreBreakdown and
a Korean-language rationale so the LLM can quote the reasoning.
Args: market: 'KOSPI' or 'KOSDAQ'. top_n: 1..10. criteria: optional override of {minPositivityScore, maxPer, minRoe}.
| Name | Required | Description | Default |
|---|---|---|---|
| market | No | KOSPI | |
| top_n | No | ||
| criteria | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that each entry includes a transparent scoreBreakdown and Korean rationale, which adds useful behavioral context. However, it does not explicitly state it is read-only or discuss side effects, but given the nature, it is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with a clear purpose sentence, then providing details in a structured Args section. Every sentence adds value with no redundant or vague statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a composite, the description covers purpose, parameters, and output structure. An output schema exists to explain return values. Missing elements like rate limits or error handling are minor, but overall it is sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The Args section explains market (enum), top_n (range 1-10), and criteria (optional override with fields). This adds significant meaning beyond the raw schema, though details of criteria fields could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a composite buy-recommendation tool that combines top gainers, quotes, news positivity, and fundamentals into a ranked list. This distinguishes it from sibling tools like get_fundamentals or get_top_gainers which are single-purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not provide explicit guidance on when to use it vs alternatives, nor does it state when not to use it. The composite nature implies it for recommendations, but no clear exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_fundamentalsget_market_overviewget_recent_newsget_stock_quoteget_top_gainersrecommend_buysScored across 6 tools
Each tool has a clearly distinct purpose: fundamentals, market overview, news, stock quote, top gainers, and a composite recommendation. No overlap or ambiguity.
Most tools follow a 'get_' prefix verb_noun pattern (e.g., get_fundamentals, get_market_overview). The exception is recommend_buys, which is still verb_noun but lacks the prefix, creating a minor inconsistency.
With 6 tools covering fundamental data, market overview, news, quotes, top gainers, and a recommend feature, the count is well-scoped for a stock information server.
The tool surface covers core stock information needs (fundamentals, quotes, news, top gainers, overview, and a composite recommendation). Minor gaps like historical prices or sector data are not critical for the stated purpose.
MCP server giving AI agents one-connection access to China A-share market intelligence: financials,
Korean stock research MCP: DART financials, global filings, daily prices and research tools.
Korea-native MCP gateway: Korean commerce, payments, messaging, gov & finance APIs for AI agents.
MCP server for stocksense-ai documentation, generated by doc2mcp.
