# MCP Stock Analyst (`neeenja/mcp-stock-analyst`) Actor

Remote MCP server for stock data: real-time quotes, fuzzy search (Chinese / pinyin / code) and historical K-lines for China A-shares, Hong Kong, Taiwan and US markets. Free upstream data source, no API key required.

- **URL**: https://apify.com/neeenja/mcp-stock-analyst.md
- **Developed by:** [Neeen Ja](https://apify.com/neeenja) (community)
- **Categories:** MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 market data calls

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## MCP Stock Analyst 📈

[English](#english) | [简体中文](#简体中文) | [繁體中文](#繁體中文)

***

<a name="english"></a>

## MCP Stock Analyst (English)

A Model Context Protocol (**MCP**) server delivering stock market data for **China A-shares, Hong Kong, US and Taiwan markets** — live quotes, smart symbol search and historical K-lines.

- **Zero-cost data**: powered by free public market-data APIs (Tencent for A-share/HK/US, Yahoo Finance for Taiwan), no API key, no quota
- **3 practical tools**: real-time quotes (batch up to 10), fuzzy search (Chinese name / pinyin / ticker code), historical candlesticks
- **Dual transport**: `stdio` (local desktop clients) + `Streamable HTTP` (remote hosting on Apify Standby)
- **Live on Apify Store**: https://apify.com/neeenja/mcp-stock-analyst — pay-per-call, no subscription

### Tools

| Tool | What it does | Example input |
|---|---|---|
| `get_quote` | Real-time quote (A-share / HK / US / Taiwan, up to 10 symbols per call) | `600519,00700,AAPL,2330.TW` |
| `search_stock` | Fuzzy search by name, pinyin or partial code | `茅台` / `GZMT` / `NVIDIA` / `台积电` / `TSMC` |
| `get_kline` | Historical candlesticks (day/week/month, 20–640 bars) | `600519` or `2330.TW`, period=`day` |

#### Taiwan stock codes

Taiwan (TWSE listed / TPEx OTC) stocks are served via Yahoo Finance. Accepted formats:

- `2330.TW` — TWSE listed (explicit)
- `5483.TWO` — TPEx OTC (explicit)
- `tw2330` — shorthand; the server auto-detects the exchange (tries `.TW` first, then `.TWO`)
- `^TWII` — Taiwan Capitalization Weighted Index (TAIEX)

### Connect (recommended: hosted endpoint)

Use the hosted MCP endpoint with any MCP client via `mcp-remote`:

```json
{
  "mcpServers": {
    "stock-analyst": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://neeenja--mcp-stock-analyst.apify.actor/mcp",
        "--header", "Authorization: Bearer ${APIFY_TOKEN}"
      ],
      "env": { "APIFY_TOKEN": "<your-apify-api-token>" }
    }
  }
}
```

Get your token from Apify Console → **Settings → API & Integrations**.

#### Or run locally (stdio)

```bash
git clone https://github.com/PanStories/mcp-stock-analyst
cd mcp-stock-analyst
npm install && npm run build
```

```json
{
  "mcpServers": {
    "stock-analyst": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-stock-analyst\\build\\index.js"]
    }
  }
}
```

#### Debug locally

```bash
npx @modelcontextprotocol/inspector node build/index.js   # interactive inspector
node e2e-test.mjs        # stdio protocol end-to-end test
node http-e2e-test.mjs   # local HTTP end-to-end test
```

### Pricing (pay-per-event)

No subscription, no monthly fee — you pay per tool call:

| Event | Charged when | Price |
|---|---|---|
| `tool-call` (primary) | each `get_quote` / `get_kline` call | **$0.02** |
| `search-call` | each `search_stock` call | **$0.005** |

**Always free:** the MCP handshake (`initialize`) and `tools/list`. Discovery costs nothing.

Every Apify account includes **$5 of free platform credit monthly** (~250 quote calls), so light users effectively pay nothing.

### HTTP endpoints (remote mode)

| Method | Path | Purpose |
|---|---|---|
| POST | `/mcp` | MCP protocol endpoint (stateless Streamable HTTP) |
| GET | `/health` | health check |
| GET | `/` | service info; answers the Apify container readiness probe |

### Deploying your own instance

```bash
npm install -g apify-cli
apify login
cd mcp-stock-analyst
apify push             # builds the Docker image on Apify's infrastructure
```

The Actor definition (`.actor/actor.json`) already enables **Standby mode** with MCP path `/mcp`. Your endpoint will be `https://<username>--mcp-stock-analyst.apify.actor/mcp` (verify in Console → Endpoints, or read `data.standbyUrl` from `GET https://api.apify.com/v2/acts/<actorId>?token=<token>`).

### Tech stack

- Node.js ≥ 18, TypeScript, official `@modelcontextprotocol/sdk`
- Data source: Tencent public market APIs (A-share/HK/US, free, no key) + Yahoo Finance chart API (Taiwan, free, no key)
- Multi-stage Docker build (`node:20-alpine`)

### Roadmap

- \[x] Pay-per-event billing
- \[x] Taiwan market support (TWSE / TPEx / TAIEX via Yahoo Finance)
- \[ ] Money flow / dragon-tiger list data
- \[ ] Financial report summaries
- \[ ] API-key auth layer (self-hosting)

### License

MIT

***

<a name="简体中文"></a>

## MCP Stock Analyst（简体中文）

一个提供 **A股 / 港股 / 美股 / 台湾股** 行情数据的 MCP (Model Context Protocol) 服务器——实时报价、智能搜索、历史K线。

- **零成本数据源**：A股/港股/美股用腾讯免费公开行情接口，台湾股用 Yahoo Finance，均无需 API key，无配额限制
- **三个实用工具**：实时报价（单次最多 10 个标的）、智能搜索（中文名/拼音/代码）、历史K线
- **双传输模式**：`stdio`（本地桌面客户端）+ `Streamable HTTP`（Apify Standby 远程托管）
- **已上架 Apify Store**：https://apify.com/neeenja/mcp-stock-analyst —— 按次付费，无订阅

### 工具列表

| 工具 | 功能 | 示例输入 |
|---|---|---|
| `get_quote` | 实时报价（A股/港股/美股/台湾股，单次最多10个） | `600519,00700,AAPL,2330.TW` |
| `search_stock` | 智能搜索代码/名称/拼音 | `茅台` / `GZMT` / `NVIDIA` / `台积电` / `TSMC` |
| `get_kline` | 历史K线（日/周/月，20–640 根） | `600519` 或 `2330.TW`，period=`day` |

#### 台湾股票代码格式

台湾股（TWSE 上市 / TPEx 上柜）走 Yahoo Finance 数据源，支持以下输入格式：

- `2330.TW` —— 上市股票（显式指定）
- `5483.TWO` —— 上柜股票（显式指定）
- `tw2330` —— 简写；服务端自动探测交易所（先试 `.TW`，再试 `.TWO`）
- `^TWII` —— 台湾加权指数（TAIEX）

### 接入方式（推荐：云端端点）

任意 MCP 客户端通过 `mcp-remote` 连接云端端点：

```json
{
  "mcpServers": {
    "stock-analyst": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://neeenja--mcp-stock-analyst.apify.actor/mcp",
        "--header", "Authorization: Bearer ${APIFY_TOKEN}"
      ],
      "env": { "APIFY_TOKEN": "<你的-Apify-token>" }
    }
  }
}
```

token 在 Apify Console → **Settings → API & Integrations** 获取。

#### 或本地运行（stdio 模式）

```bash
git clone https://github.com/PanStories/mcp-stock-analyst
cd mcp-stock-analyst
npm install && npm run build
```

```json
{
  "mcpServers": {
    "stock-analyst": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-stock-analyst\\build\\index.js"]
    }
  }
}
```

#### 本地调试

```bash
npx @modelcontextprotocol/inspector node build/index.js   # 交互式调试界面
node e2e-test.mjs        # stdio 协议端到端测试
node http-e2e-test.mjs   # 本地 HTTP 端到端测试
```

### 计费（按事件付费）

无订阅、无月费，按工具调用次数收费：

| 事件 | 触发时机 | 单价 |
|---|---|---|
| `tool-call`（主事件） | 每次行情数据调用：`get_quote` / `get_kline` | **$0.02** |
| `search-call` | 每次标的检索：`search_stock` | **$0.005** |

**永远免费：** MCP 握手（`initialize`）和 `tools/list`——发现类请求不计费。

每个 Apify 账号每月自带 **$5 平台免费额度**（按 $0.02/次约 250 次报价调用），轻度用户实际等于免费用。

### HTTP 端点（远程模式）

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/mcp` | MCP 协议端点（无状态 Streamable HTTP） |
| GET | `/health` | 健康检查 |
| GET | `/` | 服务信息；响应 Apify 容器就绪探针 |

### 部署你自己的实例

```bash
npm install -g apify-cli
apify login
cd mcp-stock-analyst
apify push             # 在 Apify 平台侧构建 Docker 镜像
```

Actor 定义（`.actor/actor.json`）已启用 **Standby 模式**，MCP 路径 `/mcp`。端点形如 `https://<username>--mcp-stock-analyst.apify.actor/mcp`（以 Console → Endpoints 页为准，或通过 `GET https://api.apify.com/v2/acts/<actorId>?token=<token>` 返回的 `data.standbyUrl` 字段获取准确地址）。

### 技术栈

- Node.js ≥ 18、TypeScript、官方 `@modelcontextprotocol/sdk`
- 数据源：腾讯公开行情接口（A股/港股/美股，免费无 key）+ Yahoo Finance chart 接口（台湾，免费无 key）
- 多阶段 Docker 构建（`node:20-alpine`）

### 路线图

- \[x] 按事件计费
- \[x] 台湾市场支持（TWSE / TPEx / 加权指数，Yahoo Finance 数据源）
- \[ ] 资金流向 / 龙虎榜
- \[ ] 财报摘要
- \[ ] 自定义 API key 鉴权层（自托管时用）

### 许可证

MIT

***

<a name="繁體中文"></a>

## MCP Stock Analyst（繁體中文）

一個提供 **A股 / 港股 / 美股 / 台股** 行情資料的 MCP (Model Context Protocol) 伺服器——即時報價、智慧搜尋、歷史K線。

- **零成本資料源**：A股/港股/美股使用騰訊免費公開行情介面，台股使用 Yahoo Finance，皆無需 API key，無配額限制
- **三個實用工具**：即時報價（單次最多 10 個標的）、智慧搜尋（中文名稱/拼音/代碼）、歷史K線
- **雙傳輸模式**：`stdio`（本機桌面用戶端）+ `Streamable HTTP`（Apify Standby 遠端託管）
- **已上架 Apify Store**：https://apify.com/neeenja/mcp-stock-analyst —— 按次計費，無訂閱

### 工具列表

| 工具 | 功能 | 範例輸入 |
|---|---|---|
| `get_quote` | 即時報價（A股/港股/美股/台股，單次最多10個） | `600519,00700,AAPL,2330.TW` |
| `search_stock` | 智慧搜尋代碼/名稱/拼音 | `茅台` / `GZMT` / `NVIDIA` / `台積電` / `TSMC` |
| `get_kline` | 歷史K線（日/週/月，20–640 根） | `600519` 或 `2330.TW`，period=`day` |

#### 台灣股票代碼格式

台股（TWSE 上市 / TPEx 上櫃）使用 Yahoo Finance 資料源，支援以下輸入格式：

- `2330.TW` —— 上市股票（顯式指定）
- `5483.TWO` —— 上櫃股票（顯式指定）
- `tw2330` —— 簡寫；伺服器自動探測交易所（先試 `.TW`，再試 `.TWO`）
- `^TWII` —— 台灣加權指數（TAIEX）

### 連接方式（推薦：雲端端點）

任意 MCP 用戶端透過 `mcp-remote` 連接雲端端點：

```json
{
  "mcpServers": {
    "stock-analyst": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://neeenja--mcp-stock-analyst.apify.actor/mcp",
        "--header", "Authorization: Bearer ${APIFY_TOKEN}"
      ],
      "env": { "APIFY_TOKEN": "<你的-Apify-token>" }
    }
  }
}
```

token 在 Apify Console → **Settings → API & Integrations** 取得。

#### 或本機執行（stdio 模式）

```bash
git clone https://github.com/PanStories/mcp-stock-analyst
cd mcp-stock-analyst
npm install && npm run build
```

```json
{
  "mcpServers": {
    "stock-analyst": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-stock-analyst\\build\\index.js"]
    }
  }
}
```

#### 本機除錯

```bash
npx @modelcontextprotocol/inspector node build/index.js   # 互動式除錯介面
node e2e-test.mjs        # stdio 協定端對端測試
node http-e2e-test.mjs   # 本機 HTTP 端對端測試
```

### 計費（按事件付費）

無訂閱、無月費，按工具呼叫次數收費：

| 事件 | 觸發時機 | 單價 |
|---|---|---|
| `tool-call`（主事件） | 每次行情資料呼叫：`get_quote` / `get_kline` | **$0.02** |
| `search-call` | 每次標的檢索：`search_stock` | **$0.005** |

**永遠免費：** MCP 握手（`initialize`）和 `tools/list`——探索類請求不計費。

每個 Apify 帳號每月自帶 **$5 平台免費額度**（按 $0.02/次約 250 次報價呼叫），輕度用戶實際等於免費用。

### HTTP 端點（遠端模式）

| 方法 | 路徑 | 說明 |
|---|---|---|
| POST | `/mcp` | MCP 協定端點（無狀態 Streamable HTTP） |
| GET | `/health` | 健康檢查 |
| GET | `/` | 服務資訊；回應 Apify 容器就緒探測 |

### 部署你自己的實例

```bash
npm install -g apify-cli
apify login
cd mcp-stock-analyst
apify push             # 在 Apify 平台側建置 Docker 映像檔
```

Actor 定義（`.actor/actor.json`）已啟用 **Standby 模式**，MCP 路徑 `/mcp`。端點形如 `https://<username>--mcp-stock-analyst.apify.actor/mcp`（以 Console → Endpoints 頁為準）。

### 技術棧

- Node.js ≥ 18、TypeScript、官方 `@modelcontextprotocol/sdk`
- 資料源：騰訊公開行情介面（A股/港股/美股，免費無 key）+ Yahoo Finance chart 介面（台股，免費無 key）
- 多階段 Docker 建置（`node:20-alpine`）

### 路線圖

- \[x] 按事件計費
- \[x] 台灣市場支援（TWSE / TPEx / 加權指數，Yahoo Finance 資料源）
- \[ ] 資金流向 / 龍虎榜
- \[ ] 財報摘要
- \[ ] 自訂 API key 驗證層（自架時用）

### 授權條款

MIT

# Actor input Schema

## Actor input object example

```json
{}
```

# Actor output Schema

## `mcpEndpoint` (type: `string`):

Streamable HTTP MCP endpoint of this Actor run. Connect an MCP client here (Authorization: Bearer \<APIFY\_TOKEN>). POST JSON-RPC messages: initialize, tools/list, tools/call.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("neeenja/mcp-stock-analyst").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("neeenja/mcp-stock-analyst").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call neeenja/mcp-stock-analyst --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,neeenja/mcp-stock-analyst"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/RfRL7Nj8f9uZtqmhc/builds/xNxeqftjS19r89xdf/openapi.json