Finance Pulse

Finance Pulse：Python 客户端和 MCP 服务

将财经新闻作为结构化、有来源的数据。Finance Pulse 将财经新闻整理为陈述：每篇文章中的一句话事实，附带情绪、重要性、股票代码、行业、来源、标题和发布时间。关于同一进展的陈述会归入话题；同一家公司的连续话题会构成一条故事线；话题则属于长期存在的主题。fintopic.news 是基于同一 API 构建的新闻首页。

同一份使用指南，以及其他指南和 API 参考文档，都可以在文档网站上找到： 从 Claude、Cursor 或 Python 使用 Finance Pulse。

这个软件包提供两种使用方式：

• Python 客户端，适用于脚本、笔记本和流水线；
• MCP 服务，让 Claude、Cursor 和其他 MCP 客户端可以直接查询新闻。

你需要一个已订阅 Finance Pulse 的 RapidAPI 密钥。 创建 RapidAPI 账号，打开 套餐页面并订阅套餐：其中有免费套餐，可用于尝试以下所有功能。然后从 RapidAPI 上该 API 的页面复制你的 X-RapidAPI-Key（端点 playground 会显示该密钥）。未订阅套餐的密钥会收到 403 响应。

从 Claude 或 Cursor 使用（MCP）

服务通过 uvx 运行，uvx 是 uv 的一部分： 请先安装 uv。软件包本身无需单独安装。

Claude Code

claude mcp add --env RAPIDAPI_KEY=YOUR_RAPIDAPI_KEY --transport stdio finance-pulse -- uvx finance-pulse

Claude Desktop 和 Cursor

• Claude Desktop：Settings > Developer > Edit Config 会打开 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。之后请完全退出并重启 Claude Desktop。
• Cursor：~/.cursor/mcp.json

{
  "mcpServers": {
    "finance-pulse": {
      "command": "uvx",
      "args": ["finance-pulse"],
      "env": { "RAPIDAPI_KEY": "YOUR_RAPIDAPI_KEY" }
    }
  }
}

如果服务无法在 Claude Desktop 中启动，通常是因为找不到 uvx：请在 "command" 中填入完整路径（which uvx 的输出，或 Windows 上 where uvx 的输出）。

uvx 会保留首次安装的版本。要升级到新版本，请将 finance-pulse 替换为 finance-pulse@latest 运行一次，或者运行 uv cache clean finance-pulse。

然后可以询问：

• “Nvidia 最近发生了什么？先概述情况，再列出关键事实和来源。”
• “哪些股票代码的报道量突然比昨天增加了？”
• “Microsoft 有哪些正在发展的故事？其中规模最大的一条是如何展开的？”
• “能源行业有哪些正在发展的热门故事？其中规模最大的一条是如何发展的？”
• “显示 Tesla 过去两周的每日新闻情绪。”

工具

工具	功能
get_symbol	一次调用获取一家公司的全部信息：各时段的数量和情绪、主要话题、故事线、相关实体、最新声明
find_symbol	根据公司名称查找代码（“micron”会找到 MU）
search_statements	按代码、行业、主题、话题、故事线、情绪、最低重要性和时间范围查找声明
trending	当前大多数媒体正在报道的动态，或近期每个时段的热门内容
find_topics	查找某个代码、行业、主题或故事线的动态，并按热度、规模或新近程度排序
get_topic	查看某项动态：数量、新闻、分析和 reddit 声明的构成、故事线，以及附带媒体来源的最新声明
storylines	将一家公司的新闻按持续发展的故事分组：事件及其后续报道和反应
get_storyline	查看一条故事线：按顺序排列的话题及其最新声明
sentiment_series	查看某个代码、行业、主题或话题的每日或每小时新闻量和情绪
screen	按新闻关注度及其变化对代码（可选仅限股票和 ETF）或行业排序，支持最近一天、一周或任意时段
themes	查看持续性主题及其新闻量和情绪，可选仅显示某个代码或行业涉及的主题
reference	查看套餐历史数据的时间范围、数量、主题 ID 和可接受的筛选值

每次工具调用通常对应一个 API 请求。结果会经过裁剪，并以小页形式返回。

在 Python 中使用

pip install finance-pulse
export RAPIDAPI_KEY=YOUR_RAPIDAPI_KEY

即使你只使用客户端，MCP SDK 也会随软件包一同安装。

from datetime import datetime, timedelta, timezone

from finance_pulse import FinancePulse

fp = FinancePulse()          # or FinancePulse("YOUR_RAPIDAPI_KEY")

# The newest key facts about a ticker
for s in fp.statements(symbol="NVDA", importance_min="high", limit=5)["data"]:
    print(s["published_at"][:16], s["sentiment"], s["statement"], f"({s['source_domain']})")

# One company in one call: counts per period, largest topics, storylines, newest statements
nvda = fp.symbol("NVDA")["data"]
week = nvda["periods"].get("w")           # a period without mentions is left out
if week:
    print(nvda["name"], week["mentions"], "mentions this week, score", week["score"])

# A company's news as continuing stories
for line in fp.storylines(symbol="MSFT", min_topics=2, sort="mentions", limit=5)["data"]:
    print(line["topics"], "topics,", line["mentions"], "mentions:", line["name"])

# Which tickers are suddenly in the news (kind= leaves out rates, central banks, countries, ...)
for row in fp.symbols(period="d", sort="change", kind=["equity", "etf"], limit=10)["data"]:
    print(row["id"], row["mentions"], row["change"])

# Daily news volume and sentiment, last two weeks
since = (datetime.now(timezone.utc) - timedelta(days=14)).strftime("%Y-%m-%dT00:00:00Z")
for b in fp.series(symbol="TSLA", interval="day", since=since)["data"]["buckets"]:
    print(b["t"][:10], b["count"], b["score"])

# What most outlets are reporting right now
for t in fp.trending(kind="live")["data"][:10]:
    print(t["sources"], "sources:", t["name"])

每个方法都会原样返回 API 的 JSON：{"data": ..., "next_cursor": ..., "snapshot": {...}} （iter_statements 和 poll_feed 会逐条生成其中的行）。snapshot 区块包含数据对应的时间（window_start、anchor、lag_days），每条声明都包含 published_at 和 indexed_at。

持续追踪新闻，不会遗漏

poll_feed 会按每条新声明进入 API 的顺序逐条生成，并将读取位置保存在文件中，因此即使重启也能继续：发生崩溃后，不会跳过任何内容，只会再次收到当时正在处理的那条声明。首次运行时，如果没有已保存的位置，就会从信息流的默认起始点开始（仅回溯有限时间，而非数据的最初记录），并在处理完第一页后首次保存读取位置。长时间暂停后，轮询器会从已保存的位置开始读取整个积压内容，追溯范围以套餐的历史数据为限；至少每 100 条声明发出一个请求；如果要重新开始，请删除游标文件。

for s in fp.poll_feed(sector="Energy", importance_min="high", cursor_file="energy.cursor.json"):
    print(s["indexed_at"], s["statement"], s["source_url"])

除非传入 interval=，否则轮询器会在每次轮询之间暂停 150 秒。每次轮询都需要一个请求（每次重试也一样），因此按默认设置持续运行整个月的轮询器大约会发出 17,000 个请求：请设置 interval=，使其符合套餐的月度配额（一个月约有 260 万秒；用这个数除以你计划用于轮询的请求数）。超时、服务器错误和短暂出现的 429（套餐的速率限制，或短时间内请求过多）会持续重试，直至问题消失；暂停时间会逐渐延长至 5 分钟，每次重试都会作为警告记录到 finance_pulse 日志记录器中。配额用尽，或 429 要求等待超过 5 分钟时，会立即抛出异常。

超过一页

rows = list(fp.iter_statements(symbol=["NVDA", "AMD"], importance_min="medium", max_items=1000))

每页 100 条需要一个请求（每次重试还会额外产生一个请求）。如果未设置 max_items，则会在 500 行后停止；max_items=None 则会一直读取到数据末尾。

错误

from finance_pulse import FinancePulseError

try:
    fp.statements(symbol="S&P")
except FinancePulseError as e:
    print(e.status, e.title, e.detail, e.param)
    # 400 Invalid symbol 'S&P' is not a ticker symbol

429 表示请求过多：套餐配额已用尽（e.quota_used_up 为 true）、达到套餐的速率限制，或同时发起的请求过多；后两种情况通常会自行恢复。请按顺序发送请求，而不要并行发送大量请求。超时和网络故障也会以 FinancePulseError 抛出，且 status 为 0；对于这些错误以及 5xx 响应，e.transient 为 true。如果 API 提供了等待时间，e.retry_after 会给出需要等待的时长。

单次调用会立即抛出所有错误。遇到临时故障或可恢复的 429 后，iter_statements 会连续重试同一页，最多五次，并逐渐延长暂停时间；poll_feed 会在这些情况持续期间不断重试（见上文）。配额已用尽和要求等待超过 5 分钟的 429 都会立即抛出。

方法

方法	端点
statements, iter_statements, statement	/v2/statements, /v2/statements/{id}
feed, poll_feed	/v2/feed
series	/v2/series
symbols, symbol, sectors	/v2/symbols, /v2/symbols/{code}, /v2/sectors
trending	/v2/trending
topics, topic	/v2/topics, /v2/topics/{id}
storylines, storyline	/v2/storylines, /v2/storylines/{id}
themes, theme	/v2/themes, /v2/themes/{id}
meta	/v2/meta

参数、响应字段和限制详见 API 参考，指南中则提供了完整的示例。fp.get("/v2/...", **params) 可调用客户端尚未提供方法的任何端点。

数据的含义与局限

• 代码是带有类型的规范实体代码。 股票和 ETF 使用其股票代码（NVDA、0700.HK）；指数、利率、货币、加密货币、大宗商品和组织则使用短代码（SPX、USD、BTC、FED）。仅查询可交易的股票代码时，使用 kind=["equity", "etf"]；要查找代码，请使用 symbols(q="name", period="window")。
• 情绪描述的是声明，而非价格预测。 某个代码的情绪是其声明标签的计数。
• 主题和故事线会自动分组，因此可能有误或不完整：它们是辅助阅读的工具，并非事件计数。
• 可查询的历史范围取决于你的套餐。 每个响应中的 window_start 会指出历史数据的起始位置，meta() 会以天数表示（window_days）；不会返回更早的声明。

完整的注意事项列表请参阅文档。

开发

pip install -e ".[dev]"
pytest

测试使用预设响应，不会发起 API 请求。

发布

1. 在 src/finance_pulse/__init__.py 和 server.json 中设置新版本号（共两处）。
2. 构建并上传到 PyPI（uv build && uv publish）。从 GitHub Actions 发布时，请使用 pypa/gh-action-pypi-publish v1.14.2 或更新版本：较旧版本会拒绝此构建写入的元数据版本。
3. 只有完成以上步骤后才能运行 mcp-publisher publish：注册表会验证 PyPI 上的包（在其描述中查找 mcp-name 行），因此必须先发布到 PyPI。

许可证

MIT