Ticker Research

한국어

Ticker Research is a read-only MCP server for researching one stock at a time from an AI chat client such as Claude or ChatGPT. It is for individual investors who want issuer filings, daily price history and a few transparent calculations in the chat, with every number labelled with its source and date.

It covers US tickers fully, and KRX listings (for example 005930) for prices, indicators and entry scenarios only. It uses two free data sources:

• SEC EDGAR (official): companyfacts financials, Form 4 insider filings and 10-K diluted EPS. SEC requires a descriptive User-Agent with a contact address, which you set in SEC_USER_AGENT.

• Yahoo Finance via yfinance (unofficial): daily bars, the latest trade, key metrics and analyst EPS consensus. yfinance is not an official Yahoo API. It can break or be rate limited, and every value from it is labelled yfinance / "unofficial" in the output.

The server holds no brokerage connection. It does not log in to any site, and it holds no account data.

Tools

Missing data is reported as unavailable with a reason code, never as zero. A section whose source is not configured (for example SEC without SEC_USER_AGENT) reports provider_not_configured. By default the latest trade (including pre-market) appears as a value marked provisional. confirmed_only=true restricts every price tool to completed daily closes.

Related MCP server: Richgo Finance MCP

Architecture

flowchart LR
    client["MCP client<br/>(Claude, ChatGPT)"] -->|"Streamable HTTP /mcp<br/>Bearer token or OAuth"| server
    subgraph server["ticker_engine (127.0.0.1:8110)"]
        auth["auth<br/>service token, optional OAuth 2.1 + owner gate"]
        tools["mcp_server<br/>7 read-only tools"]
        wire["wire<br/>compact JSON text + structuredContent,<br/>detail = summary / standard / full"]
        runtime["runtime + surface<br/>caching, refresh, concurrency limits"]
        engine["engine + evidence<br/>sections, factors, report"]
        planning["planning<br/>attractiveness, entry ladder, comparison"]
        market["market + analysis<br/>performance, indicators, EPS, freshness"]
        auth --> tools --> wire
        tools --> runtime --> engine
        tools --> planning
        tools --> market
    end
    runtime --> sec["SEC EDGAR<br/>(official)"]
    runtime --> yf["yfinance<br/>(unofficial)"]
    market --> sec
    market --> yf

Provider adapters live in ticker_engine/providers/ and are the only modules allowed to make HTTP requests (enforced by tests/ticker_engine/test_isolation.py). Engine and planning code is pure and works on the adapters' normalized rows. Every computed value keeps its inputs, formula id and source in full detail.

Response size budgets

Every tool returns structuredContent and the same object as compact JSON in a text block (MCP 2025-06-18). A client that shows the model only the text therefore sees the same fields as one that reads structuredContent.

Measured on the offline test fixtures (one year of daily bars, text block bytes):

full includes per-value provenance for every bar and the markdown report. Use it only for debugging or export.

Cross-client regression

The same server is used from Claude (claude.ai shows the model only content[].text) and ChatGPT (reads structuredContent). The test suite checks both paths offline through the real FastMCP dispatcher, with no network calls:

• test_wire_mcp.py checks that the text block of the three dict tools is the same JSON as structuredContent at each detail level. It also checks that whole-call failures return isError:true and partial results do not.

• test_market_mcp.py, test_market_tools.py and test_market_eps.py check that each analysis tool's summary holds the headline numbers, the source line and (for EPS) the bear/base/bull rows, which is what a text-only client relies on. They also check the size limits above.

• test_freshness.py checks that all price tools agree on the confirmed close and the provisional latest trade.

No graded live run across clients has been recorded for this project, so there are no pass/partial/fail numbers to report. The companion project K-invest publishes such numbers for its own tools.

Read-only safety

• Every tool is annotated readOnlyHint: true, destructiveHint: false. There are no order, transfer or account tools, and no brokerage credentials are read.

• The only state the server writes is its own cache in memory and, when OAuth is enabled, its OAuth client and grant store (SQLite in TICKER_RESEARCH_OAUTH_STATE_DIR). It writes nothing else unless you run an admin command yourself (python -m ticker_engine.auth.oauth_admin, root only).

• The service token is read from a file and kept only as a SHA-256 digest. It is never logged or echoed.

• Requests are accepted only from a direct 127.0.0.1 peer. A request with proxy headers counts as remote and needs OAuth.

• plan_entry and compare_tickers outputs are scenarios computed from public data. They are not investment advice.

Quick start

Requires Python 3.11+.

git clone <this repository> ticker-research && cd ticker-research
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest tests/ -q                      # offline; no network or credentials needed

# Service token (32-256 chars of A-Z a-z 0-9 _ -), file mode 0600
mkdir -p ~/.config/ticker-research/credentials && chmod 700 ~/.config/ticker-research/credentials
python -c 'import secrets; print(secrets.token_urlsafe(32))' > ~/.config/ticker-research/credentials/ticker-service-token
chmod 600 ~/.config/ticker-research/credentials/ticker-service-token

export CREDENTIALS_DIRECTORY=~/.config/ticker-research/credentials
export SEC_USER_AGENT="Your Name your.address@your-domain.tld"   # SEC fair-access policy; placeholder domains are rejected
ticker-research                       # serves http://127.0.0.1:8110/mcp

Point an MCP client that supports Streamable HTTP at http://127.0.0.1:8110/mcp with the header Authorization: Bearer <contents of ticker-service-token>. Then call get_ticker_research_status to check the setup.

Optional settings:

Project layout

ticker_engine/
  mcp_server.py   tool definitions and the ASGI app
  wire.py         compact JSON text block and detail levels
  runtime.py      provider composition, caching and refresh
  engine.py       snapshot sections and factor calculation
  evidence/       factor definitions and derived risk scores
  planning/       attractiveness, entry ladder, comparison (see planning/README.md)
  market/         performance, indicators, EPS scenarios, freshness
  analysis/       indicator math, checked against TA-Lib reference values
  providers/      SEC EDGAR and yfinance adapters
  auth/           service token, OAuth 2.1, owner gate
tests/            offline tests and synthetic or recorded public-data fixtures

License and support

MIT, see LICENSE.

This is a personal project published as-is. No support, maintenance or response to issues is promised. Data from yfinance is unofficial and may be wrong, delayed or unavailable. Nothing this software outputs is investment advice.