학습용 프로젝트: 에이전트(예: Claude)가 주식 데이터를 가져오고, 궁극적으로는 백테스트와 맞춤형 트레이딩 전략을 실행할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.
Python 3.11+ 필요. 아직 API 키는 필요 없습니다(현재 도구는 가입이 필요 없는 yfinance를 사용합니다).
python3 -m venv .venv
.venv/bin/pip install -e .이 명령은 .venv/에 격리된 환경을 만들고 이 프로젝트의 의존성을 설치합니다. .venv/는 gitignore 처리되어 있으므로, 이 저장소를 클론하는 사람은 무엇이든 작동시키기 전에 이 두 명령을 직접 실행해야 합니다.
Related MCP server: yfinance MCP Server
서버(src/trading_assistant_mcp/server.py)는 사용자가 직접 실행하는 것이 아니라 MCP 클라이언트(에이전트)가 stdio를 통해 실행하도록 설계되었습니다. 테스트할 수 있는 두 가지 방법이 있습니다:
1. MCP Inspector (수동 테스트, 에이전트 불필요) — 도구를 직접 호출하기 위한 브라우저 UI:
.venv/bin/mcp dev src/trading_assistant_mcp/server.py로컬 URL(예: http://127.0.0.1:6274)이 열립니다. Connect를 클릭하고 Tools 탭으로 이동한 후 도구를 수동으로 호출하세요.
uv가 설치되어 있어야 합니다(mcp dev는 위의 venv와 관계없이 내부적으로 uv run을 통해 서버를 실행합니다).
2. Claude Code (실제 에이전트) — .mcp.json에 프로젝트 범위 MCP 서버로 등록되어 있습니다. 이 디렉터리에서 Claude Code 세션을 열고 "AAPL의 가격이 얼마야?" 같은 질문을 하면 됩니다. Claude가 도구를 호출할지 여부를 스스로 결정합니다.
이식성 참고:
.mcp.json은 이 머신의.venv/bin/python에 대한 절대 경로를 하드코딩합니다. 이 저장소를 다른 곳에 클론했다면 다음을 다시 실행하세요:claude mcp add -s project trading-assistant -- /absolute/path/to/.venv/bin/python /absolute/path/to/src/trading_assistant_mcp/server.py
get_quote(symbol) — 주식 티커의 현재 가격, 일일 변동 범위, 거래량.
src/trading_assistant_mcp/
├── server.py # MCP server: wraps data functions as tools
├── data/
│ └── yfinance_client.py # plain Python, no MCP dependency — reusable/testable on its own
└── analysis/ # reserved for indicators (SMA/EMA/RSI/MACD), not yet builtserver.py는 의도적으로 얇은 어댑터입니다. mcp를 임포트하는 유일한 파일입니다. 데이터 가져오기 및 (추후) 분석 로직은 일반 Python 모듈에 유지되어 프로토콜 계층과 독립적으로 테스트하고 재사용할 수 있습니다.
백테스트와 맞춤형 자연어 전략(예: "AMD가 1% 하락할 때마다 매수, 5% 상승할 때마다 매도")에 앞서 현재 데이터 분석(캔들스틱, 펀더멘털/비율, 기술적 지표)을 진행합니다. 전체 계획은 프로젝트 결정 사항을 참조하세요.
Get historical OHLCV candlestick bars for a stock symbol.
Args: symbol: Stock ticker symbol, e.g. "AAPL" or "MSFT". period: How far back to fetch, e.g. "1mo", "3mo", "6mo". interval: Bar size, e.g. "1h", "1d".
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | 3mo | |
| symbol | Yes | ||
| interval | No | 1h |
| 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 of behavioral disclosure. It states the core behavior—returning historical rather than live data in OHLCV bar form—and describes lookback period and bar interval. It does not disclose potential edge behaviors such as timezone handling, corporate action adjustments, or error behavior for invalid symbols.
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 compact and front-loaded: one clear purpose sentence followed by a short Args block with definitions and examples. Every line adds useful information and there is no filler.
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?
With an output schema present, the return structure does not need to be explained in the description. All three parameters are covered with meaningful semantics, and the defaults are visible in the schema. The main missing pieces are explicit sibling routing and behavioral edge cases, but for a simple historical-candles endpoint the description is largely 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?
Schema description coverage is 0%, so the docstring must compensate, and it does. It defines symbol as a stock ticker with examples, period as how far back to fetch, and interval as bar size, also with examples. The schema supplies defaults, which the description does not repeat. It stops short of enumerating all valid period/interval values, but gives enough concrete guidance for correct invocation.
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 a specific verb and resource: 'Get historical OHLCV candlestick bars for a stock symbol.' This distinguishes it from sibling tools like get_quote and get_fundamentals because it is about historical price bars rather than quotes, fundamentals, or indicators. However, it does not explicitly contrast itself with those siblings.
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?
Usage is implied: this tool is for historical candle data when the agent needs OHLCV bars. The description provides no explicit guidance on when to prefer this tool over get_quote, get_fundamentals, or get_technical_indicators, nor does it mention exclusions or edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get valuation/financial ratios for a stock symbol (P/E, market cap, EPS, dividend yield, beta, 52-week range, margins, growth, etc.).
Fields may be null if not available for a given symbol/exchange.
Args: symbol: Stock ticker symbol, e.g. "AAPL" or "MSFT".
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does disclose an important trait: 'Fields may be null if not available for a given symbol/exchange'. However, it does not describe output structure, error behavior, data freshness, or symbol validation, so the behavioral picture remains partial.
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 and front-loaded: it opens with the core purpose, follows with the null-field caveat, and ends with a clear Args section. No sentence is wasted, and the structure is easy to scan.
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 with no output schema, the description is largely complete: it states the tool's purpose, lists representative fields, documents the only parameter, and flags nullability. It could be strengthened by briefly describing the expected return shape or behavior for invalid symbols, but these are minor gaps 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 schema provides only the property name 'symbol', but the description adds meaningful semantics: 'Stock ticker symbol, e.g. "AAPL" or "MSFT"'. This fully compensates for the 0% schema description coverage and gives the agent concrete examples for the single required parameter.
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 states a specific verb and resource: 'Get valuation/financial ratios for a stock symbol', and lists concrete fields such as P/E, market cap, EPS, and dividend yield. This clearly distinguishes it from sibling tools like get_quote, get_candles, and get_technical_indicators, which are about prices and technical analysis rather than fundamentals.
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 when to use the tool (when you need valuation or financial ratios) but provides no explicit guidance on alternatives or exclusions. It does not mention that get_quote should be used for current price or get_candles for historical prices, leaving the routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current price and day range for a stock symbol.
Args: symbol: Stock ticker symbol, e.g. "AAPL" or "MSFT".
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It does state what output to expect (current price and day range), but it does not discuss data reliability, delay, error handling, or whether the price is real-time or delayed. This is adequate for a simple read-only tool but leaves some behavioral details uncovered.
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 compact, front-loaded with the purpose, and includes a clearly separated 'Args:' section. Every sentence adds value, and there is no redundancy or filler.
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 with no output schema, the description is largely complete: it states the input format and the main expected output. It could be more complete by describing the return structure or noting data source, but it provides enough for an agent to call the tool with confidence.
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 schema provides no description for the 'symbol' parameter (0% coverage), but the description fully compensates by explaining the argument in plain language and giving concrete examples like 'AAPL' or 'MSFT.' This is exactly the kind of parameter semantics that helps an agent invoke the tool correctly.
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's action and resource: 'Get the current price and day range for a stock symbol.' This is specific and distinct from the siblings (fundamentals, candles, technical indicators), so an agent can confidently select this tool for quote-like data.
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 usage context is clearly implied: use when you need the current price and day range for a stock. However, it does not explicitly mention when not to use it or contrast with the sibling tools, so the guidance is clear but lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute standard technical indicators (SMA-20/50, RSI-14, MACD, Bollinger Bands, ATR-14, volume vs its 20-period average) for a stock symbol.
Fetches its own candle data internally (not via get_candles - that tool's raw output is too large to round-trip through a tool call). Needs at least 50 candles for every indicator to be non-null (fewer still works, but indicators requiring more history than is available return null).
Args: symbol: Stock ticker symbol, e.g. "AAPL" or "MSFT". period: How far back to fetch, e.g. "1mo", "3mo", "6mo". interval: Bar size, e.g. "1h", "1d".
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | 3mo | |
| symbol | Yes | ||
| interval | No | 1h |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure and does so well: it explains that the tool fetches candle data internally, why it avoids get_candles, and that insufficient history produces null values. It does not detail the exact response shape, but for a compute-only indicator tool the disclosed behavior is meaningful and sufficient.
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 compact and front-loaded: the first sentence states the capability, the second adds the key operational caveat, and the Args block gives parameter semantics in a scannable format. There is no filler, repetition, or wasted text.
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 3-parameter read/compute tool with no output schema, the description covers purpose, parameter meaning, internal data sourcing, and null behavior—enough for an agent to invoke it correctly. The only notable omission is the exact return structure, but the listed indicators and caveats provide adequate contextual coverage.
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, and it does: symbol is explained with examples, period is defined as 'how far back to fetch' with examples like '1mo', '3mo', '6mo', and interval is defined as 'bar size' with examples like '1h', '1d'. It could also state accepted formats or defaults, but the provided semantics are enough for correct invocation.
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 opens with a specific verb and resource: 'Compute standard technical indicators (SMA-20/50, RSI-14, MACD, Bollinger Bands, ATR-14, volume vs its 20-period average) for a stock symbol.' The explicit indicator list makes the tool's scope precise and clearly distinct from siblings like get_quote, get_fundamentals, and get_candles.
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 gives clear context: use this to compute indicators over a period/interval, and it explicitly warns not to prefetch candles via get_candles because that tool's raw output is too large to round-trip through a tool call. It also flags the 50-candle minimum for non-null results, though it does not explicitly discuss when to prefer get_quote or get_fundamentals.
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_candlesget_fundamentalsget_quoteget_technical_indicatorsScored across 4 tools
Each tool targets a distinct data domain: real-time quote, fundamentals, historical OHLCV, and computed indicators. Descriptions clearly separate concerns, so an agent should not confuse them.
All tools follow a consistent get_<noun> pattern with snake_case naming. The naming convention is uniform and predictable across the entire set.
Four tools is a focused, well-scoped set for a market-data-only server. Each tool covers a meaningful and non-redundant aspect of stock research.
The set covers the core read-only stock data needs: real-time price, fundamentals, historical price data, and technical indicators. Minor gaps exist, such as no symbol search/disambiguation or batch quote support, but these are workable around.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Real-time data API for AI Agents: stocks, weather, forex, logistics, search, scrape, news, IP.
Fetch current stock prices and key data for symbols across global markets. Look up companies like…
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
US stock market data for AI agents: SEC filings, financials, insider trades, 13F, options, macro.
