内容
# TradingView MCP 服务器
一个面向生产的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，暴露 TradingView 市场数据、多交易所筛选器、技术分析、情绪、新闻和内置回测引擎，供 AI 助手和自动化工具使用。
> **免责声明：** 独立开源项目 - 不隶属于 TradingView Inc. 输出仅用于研究和教育，不作为财务建议。
---
## 目录
- [功能亮点](#功能亮点)
- [架构](#架构)
- [工作流程](#工作流程)
- [项目结构](#项目结构)
- [安装](#安装)
- [配置](#配置)
- [开发](#开发)
- [测试](#测试)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [常见问题](#常见问题)
---
## 功能亮点
| 功能 | 详情 |
| --- | --- |
| **多交易所筛选器** | 加密货币、美国股票、EGX、BIST、HKEX、SSE、TWSE 等，通过静态符号列表 + TradingView 扫描器 API |
| **技术分析** | 布林带评级、RSI、多时间框架对齐、成交量突破、蜡烛图模式 |
| **回测** | 9 种策略，夏普比率、卡尔玛比率， walk-forward 过拟合检测 |
| **市场情报** | Reddit 情绪、RSS 财经新闻、Yahoo Finance 报价 |
| **弹性** | 重试/回退、内存 + 可选分布式缓存、结构化错误信封 |
| **MCP 原生** | 36 种工具，stdio 传输，与 Claude Desktop、Cursor、Copilot 等 MCP 客户端兼容 |
---
## 架构
```mermaid
flowchart TB
subgraph clients [MCP 客户端]
Claude[Claude Desktop]
Cursor[Cursor IDE]
Other[其他 MCP 主机]
end
subgraph server [tradingview-mcp-server]
Router[MCP 工具路由器]
Config[Zod 配置加载器]
Logger[结构化日志记录器]
subgraph services [服务层]
Screener[Screener 服务]
Scanner[成交量扫描器]
Backtest[回测引擎]
Yahoo[Yahoo Finance]
Sentiment[Reddit 情绪]
News[RSS 新闻]
EGX[EGX 工具]
Futures[期货工具]
end
subgraph persistence [持久化]
Memory[内存缓存]
Redis[(Redis 缓存)]
end
Provider[Screener 提供者\n重试 + 限流]
end
subgraph external [外部 API]
TV[scanner.tradingview.com]
YF[Yahoo Finance 图表 API]
Reddit[Reddit JSON API]
RSS[财经 RSS 源]
end
Claude --> Router
Cursor --> Router
Other --> Router
Router --> services
Config --> services
Logger --> services
Screener --> Provider
Scanner --> Provider
Provider --> Memory
Provider --> Redis
Provider --> TV
Yahoo --> YF
Sentiment --> Reddit
News --> RSS
Backtest --> YF
```
### 层级职责
1. **MCP 路由器** (`src/server.ts`) — 验证输入，委托给服务，返回 JSON 载荷。
2. **服务** — 领域逻辑，无 MCP 依赖；独立可测试。
3. **Screener 提供者** — HTTP 客户端，带重试、抖动、限流和缓存集成。
4. **持久化** — 可选 Redis 缓存，优雅回退到内存存储。
---
## 工作流程
### 筛选器请求流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Server as MCP 服务器
participant Cache as 缓存存储
participant TV as TradingView 扫描器
Client->>Server: top_gainers(exchange, timeframe)
Server->>Cache: 查询缓存键
alt 缓存命中
Cache-->>Server: 缓存行
else 缓存未命中
Server->>TV: POST /{market}/scan
TV-->>Server: 指标列
Server->>Cache: 存储结果
end
Server-->>Client: JSON 行或错误信封
```
### 综合分析流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Server as MCP 服务器
participant TA as 技术服务
participant Sent as 情绪服务
participant News as 新闻服务
Client->>Server: combined_analysis(symbol)
par 并行获取
Server->>TA: coin_analysis
Server->>Sent: market_sentiment
Server->>News: financial_news
end
TA-->>Server: 技术载荷
Sent-->>Server: Reddit 分数
News-->>Server: 头条新闻
Server-->>Client: 融合摘要
```
---
## 项目结构
```
tradingview-mcp/
├── src/
│ ├── index.ts # CLI 入口点
│ ├── server.ts # MCP 工具注册
│ ├── config/ # 环境验证 (Zod)
│ ├── core/ # 错误、共享类型
│ ├── indicators/ # 纯指标数学 + 指标
│ ├── persistence/ # Redis 连接 + 缓存存储
│ ├── services/ # 领域服务
│ │ ├── screener/ # TradingView 扫描器集成
│ │ ├── scanner/ # 成交量突破扫描器
│ │ ├── backtest.ts # 策略回测
│ │ ├── yahoo-finance.ts # 价格报价 + OHLCV
│ │ ├── sentiment.ts # Reddit 分析
│ │ ├── news.ts # RSS 聚合
│ │ ├── egx.ts # 埃及交易所工具
│ │ └── futures.ts # 期货概览工具
│ ├── utils/ # 验证器、HTTP、日志记录
│ └── data/coinlist/ # 每个交易所的符号列表
├── tests/unit/ # Vitest 单元测试
├── docs/AUDIT.md # 预迁移审计笔记
├── .env.example # 配置参考
├── package.json
├── tsconfig.json
└── tsup.config.ts
```
**设计决策：**
- **严格的 TypeScript** — `strict`、`noUnusedLocals`、`noUncheckedIndexedAccess` 已启用。
- **服务隔离** — MCP 层包含零业务逻辑。
- **缓存抽象** — Redis 是可选的；服务器在没有它时运行。
- **结构化错误** — 稳定的 `ErrorCode` 字符串，用于程序化处理。
---
## 安装
### 要求
- Node.js 18+
- npm 9+
- （可选）Redis 6+ 用于分布式缓存
### 设置
```bash
git clone https://github.com/your-org/tradingview-mcp.git
cd tradingview-mcp
npm install
npm run build
```
### Claude Desktop
```json
{
"mcpServers": {
"tradingview": {
"command": "node",
"args": ["D:/path/to/tradingview-mcp/dist/index.js"]
}
}
}
```
### Cursor / VS Code MCP
将您的 MCP 配置指向已构建的 `dist/index.js` 二进制文件。在更改后重启主机。
### Docker（带 Redis）
```bash
docker compose up -d
```
---
## 配置
复制 `.env.example` 到 `.env`:
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `LOG_LEVEL` | `info` | 日志详细程度 |
| `REDIS_ENABLED` | `false` | 启用分布式缓存 |
| `REDIS_URL` | — | 完整的 Redis 连接 URL |
| `REDIS_HOST` | `127.0.0.1` | Redis 主机（当 URL 未设置时） |
| `REDIS_PORT` | `6379` | Redis 端口 |
| `REDIS_KEY_PREFIX` | `tradingview-mcp:` | 键命名空间前缀 |
| `TRADINGVIEW_MCP_CACHE_TTL` | `60` | 新鲜缓存 TTL（秒） |
| `TRADINGVIEW_MCP_STALE_TTL` | `21600` | 陈旧回退 TTL（秒） |
| `TRADINGVIEW_MCP_RETRY_DELAYS` | `1.0,4.0` | 重试回退计划 |
| `TRADINGVIEW_MCP_MAX_INFLIGHT` | `2` | 并发 TA 请求上限 |
| `PROXY_ENABLED` | `false` | 启用轮换 HTTP 代理 |
参见 `.env.example` 以获取完整的列表。
---
## 开发
```bash
# 监视模式
npm run dev
# 类型检查
npm run typecheck
# lint
npm run lint
# 完整的验证管道
npm run validate
```
### 添加新的 MCP 工具
1. 在 `src/services/` 中实现逻辑。
2. 在 `src/server.ts` 中使用 Zod 参数模式注册工具。
3. 在 `tests/unit/` 下添加单元测试。
4. 运行 `npm run validate`。
---
## 测试
```bash
npm test # 运行一次
npm run test:watch # 监视模式
```
当前覆盖范围聚焦于：
- 结构化错误信封
- 时间范围/交易所验证器
- 缓存存储行为
与实时 TradingView/Yahoo API 的集成测试故意排除，以保持 CI 的确定性。
---
## 故障排除
### 空筛选器结果 vs 错误
| 症状 | 含义 | 操作 |
| --- | --- | --- |
| `[]` 空数组 | 今日无符号匹配过滤器 | 正常 - 调整过滤器 |
| `{"error":{"code":"ALL_BATCHES_FAILED"}}` | 上游失败 | 等待并重试；检查网络 |
| 超时消息 | 扫描器慢或限速 | 减少批次大小；启用缓存 |
### Redis 连接失败
服务器 **优雅降级** - 如果 Redis 在启动时不可访问，则自动使用内存缓存。检查 `REDIS_URL`、防火墙规则，并确保 Redis 接受连接。
### Windows MCP 在首次启动时超时
在配置 MCP 主机之前预构建项目（`npm run build`），以便服务器立即启动：
```bash
npm install && npm run build
```
### 节点版本错误
需要 Node 18+。使用 `node --version` 验证。
---
## 贡献
1. 分叉仓库并创建功能分支。
2. 遵循现有的 TypeScript 约定和严格的编译器设置。
3. 保持 MCP 处理程序薄 - 将逻辑放在服务中。
4. 为非琐碎的更改添加测试。
5. 在打开 PR 之前运行 `npm run validate`。
6. 编写清晰的提交消息，描述 *为什么* 而不仅仅是 *是什么*。
---
## 常见问题
**是否需要 TradingView 账户？**
否。服务器使用公共扫描器和图表端点。不需要登录或 API 密钥。
**可以在没有 Redis 的情况下运行吗？**
是的。设置 `REDIS_ENABLED=false`（默认值）。缓存仅使用内存存储。
**支持哪些交易所？**
`src/data/coinlist/` 中的符号列表和 `src/utils/validators.ts` 中的 TradingView 扫描器市场映射中的任何交易所。
**回测结果有保证吗？**
否。回测使用历史 Yahoo Finance 数据和模拟成本。过去的性能不能预测未来的结果。
**如何处理速率限制？**
调整 `TRADINGVIEW_MCP_MAX_INFLIGHT`、`TRADINGVIEW_MCP_MIN_INTERVAL_S`，并启用 Redis 缓存以减少重复的上游调用。
**这是财务建议吗？**
否。该软件是一种信息工具。请在做出财务决策之前咨询持牌专业人士。
---
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
