内容
<h1 align="center"> 霍勒斯 MCP </h1>
<p align="center">
信号扫描和股票市场研究的 MCP 服务器。提供价格查询、技术指标、观察列表、图表工具和自定义信号。
</p>
<p align="center">
<a href="#快速设置">快速开始</a> |
<a href="#工具">工具</a>
</p>
<p align="center">
<img src="docs/usage-example.png" alt="使用示例">
</p>
## 功能
- 查询当前价格、市场快照、期权、涨幅股和跌幅股
- 计算 RSI、MACD、移动平均线、贝塔值和距离历史高点等指标
- 保存可重复使用的信号（例如看涨旗形、MACD 看涨交叉、杯柄形态、金色口袋）并扫描观察列表、自定义股票代码列表或整个交易所
- 在后台运行扫描并稍后轮询状态/结果
- 生成 PNG 图表，显示价格走势、叠加层、相对强度、基本面、远期回报、广度、回撤等
- 暴露 MCP 资源，用于最近的警报、观察列表符号和远期回报研究
- 连接到您喜欢的客户端：Claude Desktop、Openclaw、Hermes 等。有关热门客户端的特定设置说明，请参见 [此处](#连接-mcp-客户端)
## 先决条件
您需要：
- Python 3.11 或更高版本：https://www.python.org/downloads/
注意：
- 图表导出使用 `kaleido`，它会自动与 Python 依赖项一起安装。
- 应用程序默认将数据库存储在 `~/.scanner_mcp/data.db`。
## 快速设置
```bash
cd /path/to/horus-mcp
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .
horus-mcp
```
Windows PowerShell：
```powershell
cd C:\path\to\horus-mcp
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .
horus-mcp
```
## 分步本地设置
<details>
<summary>显示完整的适合初学者的设置步骤</summary>
### 1. 下载项目
下载或克隆此仓库。
### 2. 在项目文件夹中打开终端
切换到项目目录：
macOS / Linux：
```bash
cd ~/Projects/horus-mcp
```
Windows PowerShell：
```powershell
cd C:\Users\YourName\Projects\horus-mcp
```
### 3. 创建虚拟环境
这使项目与设备的其他部分隔离。
macOS / Linux：
```bash
python3.11 -m venv .venv
```
Windows PowerShell：
```powershell
py -3.11 -m venv .venv
```
如果不起作用，请尝试 `python3 -m venv .venv` 或 `python -m venv .venv`。
### 4. 激活虚拟环境
macOS / Linux：
```bash
source .venv/bin/activate
```
Windows PowerShell：
```powershell
.venv\Scripts\Activate.ps1
```
当它激活时，您将在终端提示符的开头看到 `(.venv)`。
### 5. 安装项目
运行：
```bash
pip install -e .
```
这安装了依赖项和 `horus-mcp` 命令。
### 6. 启动服务器
运行：
```bash
horus-mcp
```
服务器默认使用 MCP `stdio` 传输。大多数 MCP 客户端应该在内部启动此命令，而不是要求您在单独的终端中手动运行它。
</details>
## 连接 MCP 客户端
大多数客户端需要安装的 `horus-mcp` 可执行文件的完整路径位于 `.venv` 中。
### Claude Desktop
1. 完成上述设置步骤。
2. 打开 Claude Desktop MCP 配置文件：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
3. 在 `mcpServers` 下添加 `horus-mcp` 服务器条目。
4. 重新启动 Claude Desktop。
示例配置在 macOS 上：
```json
{
"mcpServers": {
"horus-mcp": {
"command": "/Users/yourname/Projects/horus-mcp/.venv/bin/horus-mcp",
"args": []
}
}
}
```
示例配置在 Windows 上：
```json
{
"mcpServers": {
"horus-mcp": {
"command": "C:\\Users\\yourname\\Projects\\horus-mcp\\.venv\\Scripts\\horus-mcp.exe",
"args": []
}
}
}
```
如果您的 MCP 客户端无法找到可执行文件，请直接使用 Python：
macOS / Linux：
```json
{
"mcpServers": {
"horus-mcp": {
"command": "/Users/yourname/Projects/horus-mcp/.venv/bin/python",
"args": ["-m", "scanner_mcp"]
}
}
}
```
Windows：
```json
{
"mcpServers": {
"horus-mcp": {
"command": "C:\\Users\\yourname\\Projects\\horus-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "scanner_mcp"]
}
}
}
```
### Cursor
Cursor 使用与 Claude Desktop 相同的 JSON 格式。将其放在 `~/.cursor/mcp.json`（全局，所有项目）或 `<project>/.cursor/mcp.json`（项目特定）。您还可以通过 **设置 > 工具和 MCP > 新的 MCP 服务器** 添加它。
```json
{
"mcpServers": {
"horus-mcp": {
"command": "/Users/yourname/Projects/horus-mcp/.venv/bin/horus-mcp",
"args": []
}
}
}
```
### Codex CLI
Codex 使用 TOML，而不是 JSON。编辑 `~/.codex/config.toml`（或项目特定的 `.codex/config.toml`）：
```toml
[mcp_servers.horus-mcp]
command = "/Users/yourname/Projects/horus-mcp/.venv/bin/horus-mcp"
args = []
```
或从 CLI 添加：
```bash
codex mcp add horus-mcp -- /Users/yourname/Projects/horus-mcp/.venv/bin/horus-mcp
```
### OpenClaw
OpenClaw 使用 JSON，但将服务器嵌套在 `mcp.servers`（不是 `mcpServers`）下。编辑 `~/.openclaw/openclaw.json` 并重启 OpenClaw：
```json
{
"mcp": {
"servers": {
"horus-mcp": {
"command": "/Users/yourname/Projects/horus-mcp/.venv/bin/horus-mcp",
"args": []
}
}
}
}
```
### Hermes Agent
Hermes 使用 YAML。在 `config.yaml` 中的 `mcp_servers` 下添加服务器：
```yaml
mcp_servers:
horus-mcp:
command: "/Users/yourname/Projects/horus-mcp/.venv/bin/horus-mcp"
args: []
```
### Python 备用方案（所有客户端）
如果任何客户端无法找到 `horus-mcp` 可执行文件，请将 `command` 指向 venv 的 Python 并运行模块。例如，在 JSON 客户端中：
```json
{
"command": "/Users/yourname/Projects/horus-mcp/.venv/bin/python",
"args": ["-m", "scanner_mcp"]
}
```
将相同的 `command`/`args` 对适应到上面的 TOML 或 YAML 格式。在 Windows 上，在 JSON 中使用 `.venv\Scripts\` 路径并转义反斜杠（`\\`）。
## 配置
可选环境变量：
| 变量 | 功能 | 默认值 |
| --- | --- | --- |
| `SCANNER_MCP_DB` | SQLite 数据库文件路径 | `~/.scanner_mcp/data.db` |
| `SCAN_TIME` | 东部时间每日扫描时间，格式 `HH:MM` | `16:30` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `SCANNER_MCP_LOG_FILE` | 除了 stderr 之外，还写入日志文件 | 未设置 |
| `SCANNER_MCP_SCAN_WORKERS` | 后台扫描作业的工作线程 | `2` |
| `SCANNER_MCP_EXCHANGE_LIST_TTL` | 交易所符号列表的缓存寿命（秒） | `3600` |
| `SCANNER_MCP_EXCHANGE_MAX_SYMBOLS` | 交易所宇宙大小的可选上限 | 未设置 |
| `ALPHA_VANTAGE_API_KEY` | 在使用时启用 Alpha Vantage 基本面数据 | 未设置 |
| `ENABLE_DEBUG_PNG` | 启用时保存图表调试 PNG（`1`、`true`、`yes`、`on`） | 关闭 |
## 工具
### 市场数据
| 工具 | 描述 |
| --- | --- |
| `debug_quote` | 单个符号的调试助手：原始引用字段、近期历史和已解析价格字段。 |
| `get_price` | 当前或最新价格、昨日收盘价、日涨幅、成交量和市值。 |
| `get_indicators` | 具有每项指标评级和共识摘要的技术指标。 |
| `get_ath_distance` | 使用完整可用历史的距离历史高点百分比。 |
| `get_option_chain` | 具有可选到期日的股票代码期权链预览。 |
| `market_snapshot` | 主要美国指数、ETF、加密货币和波动性符号的快照。 |
| `top_gainers` | `NYSE`、`NASDAQ`、`AMEX` 或 `CRYPTO` 的当日涨幅领袖。 |
| `top_losers` | `NYSE`、`NASDAQ`、`AMEX` 或 `CRYPTO` 的当日跌幅领袖。 |
### 信号和扫描
| 工具 | 描述 |
| --- | --- |
| `list_signal_catalog` | 列出内置信号类型及其默认参数。 |
| `create_signal` | 将信号保存到 SQLite 以供后续扫描。 |
| `list_signals` | 列出所有已保存的信号。 |
| `delete_signal` | 删除已保存的信号及其警报历史。 |
| `run_scan` | 运行同步扫描，仅返回触发的匹配项。适用于较小的作业。 |
| `start_scan` | 启动后台扫描作业并立即返回 `job_id`。 |
| `get_scan_status` | 返回后台扫描作业的状态和进度计数器。 |
| `get_scan_result` | 读取已完成后台扫描作业的存储结果。 |
| `cancel_scan` | 请求取消队列中或正在运行的后台扫描作业。 |
### 观察列表
| 工具 | 描述 |
| --- | --- |
| `add_to_watchlist` | 将股票代码符号添加到保存的全局观察列表中。 |
| `remove_from_watchlist` | 从保存的全局观察列表中删除股票代码符号。 |
| `get_watchlist` | 返回当前保存的观察列表。 |
### 图表
所有图表工具在成功时返回 PNG 图像。
| 工具 | 描述 |
| --- | --- |
| `chart_price_history` | 带可选叠加层的烛线或线性价格历史，如 SMA、EMA、布林带、MA 云、斐波那契回撤、锚定 VWAP 和 P/E 子图表。 |
| `chart_price_overlay` | 多股票代码价格比较，可选归一化。 |
| `chart_ratio` | 一个资产除以另一个资产的比率图表。 |
| `chart_relative_strength` | 与基准的相对强度图表，带有移动平均线和领导力阴影。 |
| `chart_sector_rotation` | 行业或 ETF 比较，带有滚动回报面板。 |
| `chart_fundamental_overlay` | 带有叠加收入或收益条的价格图表。 |
| `chart_fundamental_momentum` | 价格、收入增长、盈利能力和估值的多面板图表。 |
| `chart_forward_returns` | 带有信号标记的价格图表和历史事件后的远期回报研究。 |
| `chart_basket_breadth` | 等权重篮子与基准的比较，带有相关性和广度面板。 |
| `chart_pairs_spread` | 带有价差或比率以及 z 评分带的配对图表。 |
| `chart_drawdown_comparison` | 跨多个股票代码的回撤比较。 |
| `chart_log_cycle` | 长期对数周期图表，适用于 BTC 等资产。 |
## MCP 资源
| 资源 | 描述 |
| --- | --- |
| `signals://triggered` | 最近触发的警报为 JSON。 |
| `signals://watchlist` | 当前观察列表符号为 JSON。 |
| `research://forward-returns/{symbol}/{event_type}` | 带有 Markdown 远期回报摘要的符号和事件类型。 |
## 免责声明
本项目仅用于研究和工具。它不是财务建议。
