Stock Analyzer MCP

> 📡 The Model Context Protocol server bundled with Stock Analyzer — 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 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)

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

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:

Profiles (filter what gets exposed)

Set `SAA_MCP_PROFILE` env var to gate which tools are visible to the LLM client:

Resources stay available in both profiles (they're read-only by definition).

How it compares

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. 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`:

{
  "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:

"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` — Claude Desktop setup, troubleshooting, conversation examples
• Launch blog post (bilingual): `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:

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`). The Stock Analyzer app itself is closed-source commercial software.

Contact

• Website: 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