# Stock Analyzer Mcp > ๐Ÿ“ก MCP server bundled with Stock Analyzer (macOS) โ€” 81 tools, deep Taiwan + US stock coverage, local SQLite, BYOK LLM. First MCP with TWSE/TPEx + institutional flow + chip data. - **Type:** MCP server - **Install:** `agentstack add mcp-kevinlin49361128-stack-stock-analyzer-mcp` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [kevinlin49361128-stack](https://agentstack.voostack.com/s/kevinlin49361128-stack) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [kevinlin49361128-stack](https://github.com/kevinlin49361128-stack) - **Source:** https://github.com/kevinlin49361128-stack/stock-analyzer-mcp ## Install ```sh agentstack add mcp-kevinlin49361128-stack-stock-analyzer-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Stock Analyzer MCP > ๐Ÿ“ก The **Model Context Protocol** server bundled with [Stock Analyzer](https://stockanalyzer.tw) โ€” a macOS desktop app for Taiwan + US stock market analysis. > > **An MCP server with deep Taiwan stock coverage** (TWSE / TPEx + three major institutional flows + chip data + monthly revenue). 95 tools across 15 categories + 6 resources. **Local-first** โ€” runs in-process inside the Electron app, no API costs, no cloud dependency. **Current version**: MCP server `1.3.0` ยท Stock Analyzer app `0.48.0-beta` ยท Updated 2026-06-30 --- ## โš ๏ธ How this MCP server actually works This repo contains the **MCP shim source** (mcp-server.js + lib/ai-tools + Dockerfile). The shim is a **thin HTTP-to-stdio bridge** โ€” when an MCP client invokes a tool, the shim proxies the call to `http://localhost:3000/api/*`, where the **Stock Analyzer desktop app's embedded Express backend** does the actual work (DB query, computation, analysis). > **The MCP server in this repo, run standalone (e.g. via `docker run`), can advertise its 95 tools through introspection but cannot execute them.** You need [Stock Analyzer](https://stockanalyzer.tw) running on the same machine for tools to actually return data. This split is intentional โ€” the analysis engine + market data + license-gated features live in the closed-source desktop app; the MCP shim is open-source (MIT) so the integration surface is fully transparent. --- ## Why this repo exists The Stock Analyzer desktop app itself is a commercial product (Lite tier free, Standard NT$1,499, Premium NT$2,999 โ€” all one-time purchases, no subscription). This repo exists to: - Open-source the **MCP shim layer** under MIT so marketplaces (awesome-mcp-servers, mcpservers.org, PulseMCP, Glama) can build & verify a working image - Provide a public canonical link for MCP discovery - Host the integration guide separately from the closed app source - Make Claude Desktop / Claude Code / agentic frameworks easy to configure against the bundled MCP server --- ## Build (Docker, for Glama / marketplaces) ```bash docker build -t stock-analyzer-mcp . docker run -i --rm stock-analyzer-mcp # stdio JSON-RPC on stdin/stdout ``` Image is ~258 MB (node:20-alpine + 2 npm deps). The build skips `better-sqlite3`, Electron, and other backend-only dependencies because the shim itself never imports them โ€” all data calls go via HTTP to the locally-running Stock Analyzer app's `/api/*` endpoints. --- ## What's in this MCP server ### 95 tools across 15 categories | Category | Tools | Examples | |---|---|---| | market (14) | Quotes, history, heatmap, sector ranking, news, FX, seasonality, ETF holdings, trading-day status | `get_stock_price`, `get_market_heatmap`, `get_seasonality` | | chips (6) | Three major institutional flows, fund flow Sankey, insider alerts, abnormal blocks, margin ranking | `get_institutional_flow`, `get_fund_flow_sankey` | | fundamentals (6) | Financial statements, monthly revenue, dividends, EPS, DCF valuation | `get_financial_statements`, `calculate_dcf` | | technical (5) | RSI / MACD / KD / Bollinger / Beta / correlation / candlestick patterns | `get_technical_indicators`, `detect_kline_patterns` | | macro (8) | FED policy, yield curve, inflation, employment, earnings calendar | `get_macro_snapshot`, `get_fed_policy_stance` | | sentiment (6) | News sentiment, market sentiment, per-stock sentiment, forecasts, entry strategies, TAIFEX put/call ratio | `get_stock_sentiment_v2`, `get_sentiment_forecasts` | | portfolio (11) | Holdings, P&L, performance, concentration, signals, trade CRUD | `get_portfolio`, `get_portfolio_concentration` | | backtest (5) | Single-stock, multi-strategy, grid search, MC factor mining, random portfolio | `backtest_strategy`, `monte_carlo_factor_mining` | | risk (6) | VaR, systemic risk, portfolio optimization, marginal/component VaR contribution, stress test, scenario stress propagation | `get_systemic_risk`, `get_risk_contribution`, `run_scenario` | | ai workflow (7) | Full-stock analysis, screener, workflows, notes, **+ deep-dive debate + daily briefing + candidate comparison + post-trade review** | `research_stock_deep_dive`, `portfolio_daily_briefing` | | thesis (7) | Investment hypothesis CRUD + quality evaluation | `upsert_thesis`, `evaluate_thesis_quality` | | watchlist (4) | Watchlist CRUD | `add_watchlist` | | alert (3) | Price alerts | `set_price_alert` | | backfill (2) | Admin data backfill | `trigger_backfill` | | forecast (5) | Price probability cone (GBM Monte Carlo), un-gameable forecast-calibration track-record, TW pre-open cross-market context, as-of knowability replay (multi-method calibration), per-stock pre-open US lead | `get_price_forecast`, `get_asof_replay`, `get_stock_preopen_lead` | Every tool carries: - **`annotations.readOnlyHint`** โ€” whether the tool modifies state (clients auto-confirm before destructive ops) - **`annotations.destructiveHint`** โ€” `delete_*` / `cancel_*` flagged true - **`annotations.idempotentHint`** โ€” `upsert_*` / `update_*` flagged true - **`_meta.tw.stockanalyzer/estimated_cost_usd`** โ€” worst-case LLM cost (most tools $0; deep-dive ~$0.16) ### 6 resources (Claude Desktop `@`-mentionable) Inject context into your conversation without burning tool calls: | Resource | Content | |---|---| | `saa://portfolio` | Full holdings (TW + US, USD/TWD unified pricing, unrealized P&L) | | `saa://watchlist` | All watchlist entries with live quotes + alert states | | `saa://thesis` | Active investment theses (hypothesis, key levels, next review dates) | | `saa://market/today` | Three major institutional flows / sector winners / systemic risk / FX | | `saa://reports/recent` | Latest portfolio briefing (free; doesn't auto-trigger LLM) | | `saa://system/info` | Server introspection (version, schema version, active profile, tool count) | ### Profiles (filter what gets exposed) Set `SAA_MCP_PROFILE` env var to gate which tools are visible to the LLM client: | Profile | Tools exposed | Use case | |---|---|---| | `default` (omit) | All 95 | Your personal Claude Desktop | | `safe_readonly` | 80 read-only tools | Shared / untrusted LLM clients โ€” blocks `add_trade` / `delete_*` / `upsert_thesis` / `set_price_alert` / etc. | Resources stay available in both profiles (they're read-only by definition). --- ## How it compares | Server | TW coverage | US coverage | Local | License model | |---|---|---|---|---| | Alpha Vantage MCP | โš ๏ธ Delayed quotes only | โœ… Full | โŒ Cloud API | Pay per call | | Financial Datasets MCP | โŒ None | โœ… Full | โŒ Cloud API | Subscription | | EODHD MCP | โš ๏ธ EOD only | โœ… Full | โŒ Cloud API | Subscription | | Lambda Finance | โŒ None | โœ… Full + options | โŒ Cloud | Subscription | | Stockflow (Yahoo) | โš ๏ธ Spotty TW data | โœ… Full | โŒ Cloud | Free (rate-limited) | | **Stock Analyzer MCP** | โœ… **Deep TWSE + TPEx + institutional + chip** | โœ… Full | โœ… **Local SQLite** | One-time license (Lite free) | For non-Taiwan readers: Taiwan stock market has its own data ecosystem (TWSE, TPEx OpenAPI, three major institutional investors, monthly revenue reporting) that's nearly absent from English-speaking financial data platforms. If you want an AI agent that can answer "How are TSMC's institutional investors trading lately?" or "Find me TW small-caps with >30% YoY revenue growth", Stock Analyzer MCP is built for exactly this โ€” deterministic TW chip/institutional/revenue tools that English-focused MCP servers generally lack. --- ## Quickstart: Claude Desktop ### 1. Install Stock Analyzer Get the free Lite tier from [stockanalyzer.tw](https://stockanalyzer.tw). Version `0.47.4-beta` or later ships MCP server v1.2.0. ### 2. Configure Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```jsonc { "mcpServers": { "stock-analyzer": { "command": "/Applications/Stock Analyzer.app/Contents/Resources/app.asar.unpacked/bin/saa-mcp", "env": { "PORT": "3000" } } } } ``` > **Why the wrapper?** Running `node mcp-server.js` directly hits a `better-sqlite3` ABI mismatch (the binding is compiled for Electron's Node, not the system's). The `bin/saa-mcp` wrapper auto-finds the SAA Electron runtime and runs the MCP server with `ELECTRON_RUN_AS_NODE=1`. Older configs that point to `node` will need updating. ### 3. (Optional) Restrict to read-only mode If the LLM client isn't fully trusted (shared Claude project, third-party agent), add: ```jsonc "env": { "PORT": "3000", "SAA_MCP_PROFILE": "safe_readonly" } ``` This blocks 15 write tools (`add_trade`, `delete_trade`, `upsert_thesis`, `set_price_alert`, etc.) but keeps all read tools + all 6 resources. ### 4. Fully restart Claude Desktop (`cmd+Q` then reopen) ### 5. Try it > "List all SAA stock-analyzer tools" > > "Analyze 2330 โ€” institutional flow last month + 3-month momentum + radar score + give me a buy/sell view" > > "@saa://portfolio โ€” what's my biggest concentration risk?" > > "Compare 2330, 2454, and 3008 as candidates. Include their theses if they exist." Claude will orchestrate multiple tool calls (or `@`-mentions for resources) and synthesize a research report. --- ## Headline tools (2026-05-18) ### ๐ŸŽญ `research_stock_deep_dive` โ€” Premium tier 5 specialized AI agents debate in parallel: - ๐Ÿ‚ Bull (only sees evidence supporting an upside thesis) - ๐Ÿป Bear (only sees evidence supporting a downside thesis) - ๐Ÿ“ฐ Sentiment (news + social signals) - ๐Ÿ›ก๏ธ Risk (volatility, drawdown history, regime context) - ๐ŸŽฏ Synthesizer (sees all four; produces a 6-level action: `strong_buy` โ†’ `avoid`) Each agent uses a distinct subset of the 95 tools. Output includes per-agent reasoning + final action + confidence score. ~$0.16/call LLM cost (Anthropic Sonnet / OpenAI). ### ๐ŸŒ… `portfolio_daily_briefing` โ€” Lite tier Pre-market or post-market portfolio briefing. Aggregates current holdings, unrealized P&L, sector exposure, relevant macro / institutional flow into an actionable summary. - `mode='get'` โ†’ reads the latest cached briefing (free, instant) - `mode='generate'` โ†’ runs a fresh one (~10-20s, ~$0.04/call LLM cost) ### ๐Ÿ” `compare_investment_candidates` โ€” Lite, cost $0 Side-by-side deep analysis of 2-5 candidate stocks. Parallel fan-out of `get_full_stock_analysis` (fundamentals + technical + chip + institutional + levels) per candidate, plus existing thesis status. **Deterministic** โ€” the agent sees raw evidence rather than an LLM-synthesized opinion, which empirically produces better reasoning. ### ๐Ÿ““ `post_trade_review` โ€” Lite, cost $0 Past-N-days reflection. Aggregates `analyze_trade_performance` (FIFO P&L, win rate, hold time) + `get_trade_journal` (recent trades) + `get_portfolio_signals` (current state). Auto-detects observable patterns: - `low_win_rate` ( avg win) โ†’ poor stop-loss discipline Hands the agent objective indicators to write narrative review against. --- ## Documentation - **Full MCP usage guide** (zh-TW + en): [`MCP-USAGE-GUIDE.md`](./MCP-USAGE-GUIDE.md) โ€” Claude Desktop setup, troubleshooting, conversation examples - **Launch blog post** (bilingual): [`docs/mcp-launch-2026-05.md`](./docs/mcp-launch-2026-05.md) โ€” context on the 2026 MCP finance landscape + why TW coverage was the gap - **Tool reference**: bundled inside the app at Settings โ†’ ๐Ÿ”Œ MCP / Agent --- ## Design philosophy - **Local-first**: All data lives in `~/.twse-analyzer/stock_history.db` (SQLite, single file). MCP server runs in-process inside the Electron app via stdio transport. - **BYOK LLM**: SAA itself has an AI Hub that consumes the same 95 tools. Bring your own keys (Claude / GPT / Gemini / Ollama). The MCP server itself isn't tied to any LLM โ€” it just exposes deterministic data + a few LLM-backed aggregators. - **Transparent methodology**: 16 bilingual methodology pages (zh-TW + en) explain every analytical tool's formula, data source, and limitations. Available at `/methodology.html` inside the app. - **No active trading signals**: Research output only โ€” not order execution. Regulatory + product positioning decision. - **Cost honesty**: Every tool surfaces its worst-case LLM cost upfront via `_meta.tw.stockanalyzer/estimated_cost_usd`. No hidden cloud-API spend. --- ## Versioning The MCP server uses two version numbers: | Field | Meaning | Bump on | |---|---|---| | `server_version` | SAA MCP binary version (shown at `initialize`) | Each SAA app release | | `tools_schema_version` (in `saa://system/info`) | Tool/resource shape version | Tool added/removed/renamed/required-changed | Rules: - **patch** โ€” additive (new tool, new resource) - **minor** โ€” new required param, new enum restriction, `readOnlyHint` change - **major** โ€” rename, removal, required-keys change Current: server `1.2.0`, schema `1.2.0`. Changelog inside `mcp-server.js` header. --- ## License This documentation repo is MIT licensed (see [`LICENSE`](./LICENSE)). The Stock Analyzer app itself is closed-source commercial software. --- ## Contact - **Website**: [stockanalyzer.tw](https://stockanalyzer.tw) - **Email**: hello@stockanalyzer.tw - **Issues**: Use GitHub Issues on this repo for MCP integration questions - **For app feature requests or bug reports**: email above ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [kevinlin49361128-stack](https://github.com/kevinlin49361128-stack) - **Source:** [kevinlin49361128-stack/stock-analyzer-mcp](https://github.com/kevinlin49361128-stack/stock-analyzer-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-kevinlin49361128-stack-stock-analyzer-mcp - Seller: https://agentstack.voostack.com/s/kevinlin49361128-stack - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.