Finance Pulse

Finance Pulse：Python クライアントと MCP サーバー

金融ニュースを、出典付きの構造化データとして提供します。Finance Pulse は、金融ニュースをステートメントとして提供します。各記事から抽出した一文の事実に、センチメント、重要度、ティッカー、セクター、出典、見出し、公開時刻が付いています。同じ動向に関するステートメントはトピックにまとめられます。ある企業のトピックが互いに続く場合はストーリーラインを形成し、トピックは常設のテーマに属します。 fintopic.news は、同じ API を使ったトップページです。

他のガイドや API リファレンスとともに、同じセットアップガイドをドキュメントサイトでご覧いただけます： Claude、Cursor、または Python から Finance Pulse を使う。

このパッケージには、利用方法が 2 つあります：

• スクリプト、ノートブック、パイプライン向けのPython クライアント；
• Claude、Cursor、その他の MCP クライアントからニュースを直接クエリできるMCP サーバー。

Finance Pulse に登録済みの RapidAPI キーが必要です。 RapidAPI アカウントを作成し、プランページを開いてプランに登録してください。以下の機能をすべて試せる無料プランもあります。次に、RapidAPI の API ページから X-RapidAPI-Key をコピーします（エンドポイントのプレイグラウンドに表示されます）。プランに登録されていないキーを使うと、403 が返されます。

Claude または Cursor から使う（MCP）

サーバーは uv に含まれる uvx で実行します。まず 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 について進行中のストーリーは何ですか？最も大きなものがどのように展開したかも教えてください。」
• 「Energy で進展中の主なストーリーは何ですか？最も大きなものがどのように広がったかも教えてください。」
• 「過去 2 週間の Tesla の日ごとのニュースセンチメントを表示してください。」

ツール

ツール	機能
get_symbol	1 回の呼び出しで、1 社またはその他のエンティティに関するすべての情報を取得します。期間ごとの件数とセンチメント、最大のトピック、ストーリーライン、関連エンティティ、最新の発言が含まれます
find_symbol	企業名から企業コードを検索します（「micron」なら MU が見つかります）
search_statements	シンボル、セクター、テーマ、トピック、ストーリーライン、センチメント、重要度の下限、期間で発言を検索します
trending	現在、最も多くの媒体が報じている動向、または直近の各時間枠での上位動向を取得します
find_topics	シンボル、セクター、テーマ、ストーリーラインについて、勢い、規模、新しさに基づいて動向を検索します
get_topic	1 つの動向について、件数、ニュース・分析・reddit の発言の内訳、ストーリーライン、媒体名付きの最新の発言を取得します
storylines	1 社のニュースを、継続中のストーリー（出来事とその続報や反応）ごとにまとめます
get_storyline	1 つのストーリーラインについて、順序付きのトピックと最新の発言を取得します
sentiment_series	シンボル、セクター、テーマ、トピックの日次または時間ごとのニュース量とセンチメントを取得します
screen	直近 1 日、1 週間、または任意の期間について、ニュースの注目度とその変化でシンボル（株式と ETF のみに限定可能）またはセクターを順位付けします
themes	継続的なテーマとその量、センチメントを取得します。特定のシンボルまたはセクターが含まれるテーマのみに限定することもできます
reference	プランで利用できる履歴の範囲、件数、テーマ ID、受け付けられるフィルター値を確認します

各ツールの呼び出しは通常、API リクエスト 1 回分です。結果はサイズが調整され、少数のページに分けて返されます。

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 は、その行を 1 件ずつ返します）。snapshot ブロックには、データが参照する時刻（window_start、anchor、lag_days）が含まれ、各発言には published_at と indexed_at が含まれます。

ニュースを見逃さずに追跡する

poll_feed は、新しい発言を API に登録された順に返し、位置情報をファイルに保存するため、再起動後も処理を続けられます。クラッシュしても項目が飛ばされることはなく、処理中だった発言だけが再度配信されます。保存済みの位置情報がない初回実行では、フィードのデフォルトの開始地点（データの先頭ではなく、限られた期間だけ遡った地点）から始まり、最初のページの処理が済んだ時点で位置情報が初めて保存されます。長い間隔を空けた場合、ポーラーは保存済みの位置から、プランで参照できる履歴の範囲まで、未処理分をすべて読み込みます。100 件ごとに少なくとも 1 回リクエストします。最初からやり直すには、カーソルファイルを削除してください。

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 秒待機します。ポーリング 1 回につきリクエスト 1 回（リトライも同様）が必要なため、デフォルト設定で 1 か月間ポーラーを実行すると、約 17,000 回のリクエストが発生します。プランの月間上限に合わせて interval= を設定してください（1 か月は約 260 万秒です。ポーリングに使いたいリクエスト数で割ってください）。タイムアウト、サーバーエラー、一時的な 429（プランのレート制限、または一度にリクエストしすぎた場合）は、発生している間リトライされます。待機時間は最長 5 分まで延び、リトライのたびに finance_pulse ロガーに警告として記録されます。クォータを使い切った場合、または 5 分を超える待機を求める 429 が発生した場合は、すぐに例外が発生します。

複数ページの取得

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

100 件の各ページにつきリクエストが 1 回必要です（リトライ 1 回につき、さらに 1 回必要です）。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）、プランのレート制限に達した、または同時に開いているリクエストが多すぎる場合です。後者の2つは通常、時間が経てば解消します。リクエストは多数を並行して送るのではなく、1つずつ送信してください。タイムアウトやネットワーク障害も FinancePulseError として発生し、status は 0 になります。これらの場合と 5xx の応答では、e.transient が true になります。API が時間を指定した場合、e.retry_after は待機する時間を示します。

単一の呼び出しでは、すべてのエラーが直ちに発生します。iter_statements は一時的な障害または時間が経てば解消する 429 の後、ページの取得を連続で最大5回再試行し、待機時間を徐々に延ばします。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か所）で新しいバージョンを設定します。
2. PyPI 向けにビルドしてアップロードします（uv build && uv publish）。GitHub Actions から実行する場合は、pypa/gh-action-pypi-publish の v1.14.2 以降を使用してください。それより古いバージョンでは、このビルドが書き込むメタデータのバージョンが拒否されます。
3. その後にのみ mcp-publisher publish を実行します。レジストリは PyPI 上のパッケージを検証します（説明文の mcp-name 行を確認するため、リリースが先に公開されている必要があります）。

ライセンス

MIT