stock-scanner-mcp

stock-scanner-mcp

一个模块化 MCP 服务，可供 Claude Code 和 Claude Desktop 使用，提供对股票和加密货币市场数据的实时访问。通过一个服务扫描市场、查看技术指标、监控内幕交易、跟踪财报、分析期权流，并可选择保存自己的观察列表和投资论点笔记。

69 个工具，分布在 15 个模块中——其中 11 个模块无需任何 API 密钥即可使用，包括可选的有状态 Market Workspace。

快速开始

只需三步即可获得完整体验：配置服务、安装交易技能并设置工作区。

第 1 步 — 将服务添加到 MCP 配置

将以下完整配置块复制到配置文件中：

• Claude Code： ~/.claude.json（全局）或 .mcp.json（项目本地）
• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "stock-scanner": {
      "command": "npx",
      "args": ["-y", "stock-scanner-mcp", "--enable-workspace"],
      "env": {
        "FINNHUB_API_KEY": "your-key-here",
        "ALPHA_VANTAGE_API_KEY": "your-key-here",
        "FRED_API_KEY": "your-key-here"
      }
    }
  }
}

无需 API 密钥即可立即使用 49 个工具。API 密钥可选且免费，可解锁另外 20 个工具，用于获取实时报价、新闻、财报和经济数据。有关获取方式，请参阅下方的 API 密钥。

最简配置——如果不需要工作区或 API 密钥，请改用以下配置：

{
  "mcpServers": {
    "stock-scanner": {
      "command": "npx",
      "args": ["-y", "stock-scanner-mcp"]
    }
  }
}

这样即可使用 42 个无状态工具，且不会在本地存储数据。

保存后重启 Claude Desktop。Claude Code 会自动读取配置。

Claude Code 快捷方式——通过插件安装，无需执行第 1 步和第 2 步。 如果你使用 Claude Code，可以跳过上面的手动配置，通过两条命令安装所有内容：

/plugin marketplace add yyordanov-tradu/stock-scanner-mcp
/plugin install stock-scanner@tradu-marketplace

运行 /reload-plugins，然后运行 /mcp——你应该会看到 stock-scanner 服务已连接。首次启动时会运行 npx -y stock-scanner-mcp，下载一次软件包（之后会缓存）。插件默认启用工作区（数据存储在 ~/.stock-scanner-mcp），并从环境中传入可选的 API 密钥（FINNHUB_API_KEY、ALPHA_VANTAGE_API_KEY、FRED_API_KEY）；没有密钥的模块会自动跳过。

插件已包含所有技能——请勿执行第 2 步。 插件附带全部 19 个技能，并以 stock-scanner: 命名空间加载，例如 /stock-scanner:analyze-stock AAPL、/stock-scanner:morning-briefing、/stock-scanner:setup-market-workspace。如果同时运行第 2 步安装程序，还会将另一套不带前缀的技能复制到 ~/.claude/skills/，两套技能会发生冲突——第 2 步仅适用于手动安装（非插件方式）。安装后直接进入第 3 步，并使用带命名空间的命令：/stock-scanner:setup-market-workspace。

第 2 步 — 安装交易技能

如果通过上方的插件安装，请跳过此步骤——插件已包含这些技能（名称格式为 stock-scanner:<name>）。此步骤仅适用于第 1 步中的手动配置。

在终端中运行此命令：

npx -p stock-scanner-mcp stock-scanner-install-skills

这会将 19 个斜杠命令（例如 /morning-briefing、/analyze-stock AAPL、/setup-market-workspace）安装到 ~/.claude/skills/，以便在每次 Claude Code 会话中使用。完整列表请参阅交易技能。

第 3 步 — 设置工作区

在 Claude Code 中运行 /setup-market-workspace。它会问你三个简单的问题：

> /setup-market-workspace

Setting up your market workspace — I'll ask a few quick questions to get started...

1. What kind of trader or investor are you?
   (e.g., options trader, swing trader, long-term investor, crypto-focused)

   → "I'm mostly a swing trader, also watch crypto"

2. Which names or assets should I save to your core watchlist?
   (e.g., AAPL, MARA, BTC, Gold)

   → "MARA, HOOD, SOFI, BTC, ETH"

3. Do you want a daily or weekly market review?

   → "Daily"

回答后，它会保存你的个人资料并创建一个 core 观察列表：

✓ Workspace saved

  Profile     swing trader | daily review
  Watchlist   core — MARA, HOOD, SOFI, BTC, ETH

你也可以跳过该技能，直接向 Claude 提问：“设置我的工作区——我是波段交易者，请创建一个包含 MARA、HOOD、BTC 的核心观察列表，并进行每日回顾。”

就是这么简单。 现在，你拥有 69 个工具、19 个技能和个性化工作区。试试 /workspace-morning-brief，开始你的首次定制市场扫描。

你可以做什么

"What are the top gaining stocks today?"
"Show me technicals for AAPL on the hourly timeframe"
"Any insider trades for TSLA in the last 30 days?"
"What's the options chain for AAPL expiring next Friday?"
"What's the current fed funds rate and CPI trend?"
"Convert $10,000 USD to EUR"
"Set up a core watchlist with MARA, HOOD, and BTC"
"Give me a personalized morning brief for my saved watchlist"

亮点

• 股票扫描 — 使用自定义筛选条件，按价格、RSI、成交量和市值筛选
• 技术分析 — 跨多个时间周期分析 RSI、MACD、布林带、移动平均线和枢轴点
• 期权流 — 提供包含希腊值的期权链、异常活动检测、最大痛点和隐含波动幅度
• 内部人士交易 — 解析 Form 4 交易记录，提供买入、卖出和授予详情
• 财报与新闻 — 提供日历、分析师评级、公司新闻和卖空兴趣
• 加密货币 — 实时行情、技术指标、热门币种和市场统计数据
• 宏观经济 — CPI、GDP、联邦基金利率、经济日历和收益率曲线数据
• 外汇 — 来自 ECB 的 31 种货币对、货币换算和历史汇率
• 市场情绪 — CNN 恐惧与贪婪指数、加密货币恐惧与贪婪指数
• Market Workspace — 保存交易档案、命名观察列表和投资论点笔记，跨会话实现个性化工作流

交易技能

19 个现成工作流，可将多个工具串联起来，进行结构化分析。每项技能会并行调用 5–14 个工具，并输出包含方向、置信度和关键价位的结论。

缺少可选 API 密钥时，技能仍可正常运行，但功能会相应降级。工作区技能要求在服务器配置中使用 --enable-workspace。

npx -p stock-scanner-mcp stock-scanner-install-skills                    # all 19 skills
npx -p stock-scanner-mcp stock-scanner-install-skills --scope project    # project only (.claude/skills/)
npx -p stock-scanner-mcp stock-scanner-install-skills --category macro   # one category
npx -p stock-scanner-mcp stock-scanner-install-skills --category workspace # workspace skills only
npx -p stock-scanner-mcp stock-scanner-install-skills --list             # list without installing
npx -p stock-scanner-mcp stock-scanner-install-skills --force            # overwrite existing

完整目录请参阅 skills/README.md。

Market Workspace

Market Workspace 是一个可选的有状态层，可跨会话记住你的交易背景——包括交易风格、命名观察列表，以及每个标的的投资论点笔记。/workspace-morning-brief 等技能会利用这些信息提供个性化市场扫描，而非通用扫描。

你可以用它做什么

• /workspace-morning-brief — 个性化盘前扫描，会读取你的档案和观察列表，检查列表中标的的财报、新闻和价格走势，并突出当天的重要信息
• 添加更多观察列表 — 告诉 Claude：“创建一个名为 ‘earnings’ 的观察列表，包含 AAPL、MSFT、GOOG”
• 跟踪投资论点 — 保存每个股票代码对应的分析依据，让系统为你持续监控（见下文）
• 随时更新 — “将 NVDA 添加到我的核心观察列表”或“将我的回顾频率改为每周”

投资论点追踪

按股票代码保存你的投资逻辑——方向、关键价位、催化因素和时间范围——以便系统跨会话进行监控。

保存投资论点：

"My thesis on NIO: bullish above $6.35, that confirms the uptrend. Below it the setup is invalid."

Claude 会保存结构化的投资论点：

**实际运行方式：**运行 /workspace-morning-brief 时，简报会将你保存的投资论点与实时价格走势进行交叉比对：

• NIO 跌至 $6.10 → “NIO 跌破了你设定的 $6.35 论点底线——请重新评估。”
• NIO 涨至 $7.20 → “NIO 守住了你设定的 $6.35 价位——上升趋势论点依然成立。”

没有投资论点时，简报只会报告价格变动。有了投资论点，它还会告诉你这次波动是否与你的计划有关。

每个投资论点包含五个字段：summary、bullCase、bearCase、catalyst 和 timeframe。每个工作区最多可保存 200 个投资论点。

配置参考

数据存储在本地的 workspace.json 中——不会同步到云端，也不会进行外部调用。如果省略 --enable-workspace，服务将保持完全无状态，不会写入任何本地数据。

如需查看完整的工作区工具列表，请参阅下方的工具参考。

文档

• 安装与设置 — 在 Claude Code 或 Cursor 中运行 MCP 服务
• 交易技能 — 用于专业分析的现成工作流
• Sidecar HTTP API — 面向非 MCP 客户端的 REST 端点
• Docker 部署 — 在容器中运行并持久保存工作区数据
• 常见问题与故障排除 — 常见问题及解决方案

模块

设置 API 密钥后，模块会自动启用。无需密钥的模块始终启用，但 workspace 除外，它需要 --enable-workspace。

如需查看所有工具及其描述的完整列表，请参阅下方的完整工具参考。

完整工具参考（69 个工具）

TradingView — 股票扫描（无需 API 密钥）

TradingView — 加密货币（无需 API 密钥）

SEC EDGAR — 文件与所有权（无需 API 密钥）

CoinGecko — 加密货币情报（无需 API 密钥）

Options — 期权链、希腊值与异常活动（无需 API 密钥）

Options CBOE — 看跌/看涨情绪（无需 API 密钥）

情绪 — 恐惧与贪婪（无需 API 密钥）

Frankfurter — 外汇汇率（无需 API 密钥）

Reddit — 热门股票代码与情绪（无需 API 密钥）

市场广度 — 广度指标（无需 API 密钥）

统一市场 — 智能路由（无需 API 密钥）

Workspace — 个性化上下文（可选，无需 API 密钥）

仅在使用 --enable-workspace 启动服务时启用。

Finnhub — 新闻、财报与宏观数据（需要 FINNHUB_API_KEY）

Alpha Vantage — 基本面与历史数据（需要 ALPHA_VANTAGE_API_KEY）

FRED — 美国经济数据（需要 FRED_API_KEY）

配置

CLI 选项

npx -y stock-scanner-mcp --modules tradingview,sec-edgar    # Enable specific modules only
npx -y stock-scanner-mcp --default-exchange NYSE             # Set default exchange
npx -y stock-scanner-mcp --enable-workspace                  # Turn on local workspace tools
npx -y stock-scanner-mcp --enable-workspace --data-dir /tmp/market-workspace  # Custom data directory
npx -y stock-scanner-mcp --help                              # Show all options

API 密钥（可选）

以下三个密钥均为免费，无需信用卡：

将它们添加到 MCP 配置中的 env 区块（参见快速开始）。

与其他 MCP 客户端配合使用

任何支持 stdio 服务的 MCP 客户端都可以运行此软件包。使用快速开始中的同一份 JSON 配置。如果你的客户端无法调用 npx，请先安装软件包，然后将客户端指向已安装的二进制文件。

HTTP Sidecar

一个可选的 HTTP 服务器，可将所有工具作为 REST 端点公开，供非 MCP 集成使用（GPT Actions、聊天 UI、大模型流水线）。它包含 OpenAPI 3.1 规范，可用于自动发现工具。

npx stock-scanner-sidecar              # Start on port 3200
npx stock-scanner-sidecar --port 8080  # Custom port

# Optional: Enable the stateful Market Workspace via HTTP
npx stock-scanner-sidecar --enable-workspace --data-dir ./my-data

# Access the OpenAPI spec
curl http://localhost:3200/openapi.json

有关端点详情，请参阅 Sidecar HTTP API。

69 个工具作为 REST 路由公开，包括 /market/quote、/options/chain、/workspace/profile 等。

速率限制

所有模块都使用内存 TTL 缓存，以尽量减少 API 调用。

开发

npm install && npm run build && npm test
npm run lint               # TypeScript type checking
npm run validate-tools     # Tool description quality check
npm run validate-doc-tools # Skill/command tool reference check

可信度材料

• 基准测试示例
• 对话记录示例
• 延迟与可靠性概览

src/
├── index.ts              # MCP server entry + prompt definitions
├── config.ts             # CLI arg parsing
├── registry.ts           # Module auto-discovery and filtering
├── modules/
│   ├── tradingview/      # 10 tools — stock scanning, quotes, technicals, sectors, indices
│   ├── tradingview-crypto/ # 4 tools — crypto scanning and technicals
│   ├── sec-edgar/        # 6 tools — filings, insider trades, holdings
│   ├── coingecko/        # 3 tools — crypto market data
│   ├── options/          # 5 tools — options chains, Greeks, unusual activity, implied move
│   ├── options-cboe/     # 1 tool  — CBOE put/call ratio sentiment
│   ├── workspace/        # 7 tools — stateful profile, watchlists, thesis notes
│   ├── finnhub/          # 9 tools — quotes, news, earnings, analyst ratings, short interest
│   ├── alpha-vantage/    # 5 tools — quotes, fundamentals, dividends
│   ├── fred/             # 4 tools — economic calendar, indicators, historical data
│   ├── sentiment/        # 2 tools — Fear & Greed indexes (market + crypto)
│   ├── frankfurter/      # 5 tools — forex exchange rates (ECB, 31 currencies)
│   ├── reddit/           # 4 tools — trending tickers, mentions, sentiment, watchlist scan from Reddit
│   └── unified-market/   # 3 tools — smart provider routing for quotes/profiles/technicals
├── sidecar/
│   ├── index.ts          # HTTP sidecar entry point (port 3200)
│   ├── routes.ts         # Declarative URL routing table
│   └── server.ts         # Dynamic HTTP request handler
└── shared/
    ├── http.ts           # HTTP client with timeouts and key sanitization
    ├── cache.ts          # In-memory TTL cache
    ├── types.ts          # ToolDefinition, ToolResult, helpers
    ├── resolver.ts       # Ticker/exchange resolution
    └── utils.ts          # withMetadata error wrapper

许可证

MIT