QualityScreener

Quality Screener MCP サーバー

Quality Screener の株式スクリーニングエンジンを、AI エージェント（Claude、Cursor、その他の MCP クライアント）向けのツールとして提供する、スタンドアロンの Model Context Protocol（MCP）サーバーです。

接続すると、エージェントはスコア付けされた銘柄群のスクリーニングやフィルタリング、カスタム品質スコアの計算、スコア履歴の確認、保存済みのスコアリングシステムの管理、共有可能なスクリーニングリンクの生成を行えます。すべて、ウェブダッシュボードでユーザー自身が確認できるものと同じデータに対し、サインイン中のユーザーとして実行されます。

• SDK 依存なし。 サーバーは、公開されている Quality Screener API の薄い HTTP レイヤーです。バックエンドの Python パッケージには依存しません。各ツールは REST エンドポイントを呼び出し、JSON ペイロードを返すだけです。
• マルチテナントで、認証情報は不要。 HTTP 経由でデプロイする場合、サーバー自体は認証情報を保存しません。各リクエストには呼び出し元自身のアクセストークンが含まれ、サーバーはそれを API に転送します。そのため、単一の公開デプロイメントで共有アカウントを使うことなく、多数のユーザーにサービスを提供できます。

---

目次

• 仕組み
• クイックスタート（リモート）
• ローカルでの実行
• 設定
• 認証
• ツール
• CustomScoreConfig の使用
• MCP クライアントの接続
• デプロイ
• Vercel へのデプロイ
• 開発
• プライバシーポリシー
• サポート
• ライセンス

---

仕組み

┌─────────────┐   MCP (stdio | streamable-HTTP)   ┌──────────────────┐   HTTPS   ┌──────────────────────┐
│  AI agent   │ ────────────────────────────────► │  qscreener-mcp   │ ────────► │ Quality Screener API │
│ (MCP client)│ ◄──────────────────────────────── │   (this server)  │ ◄──────── │   (FastAPI backend)  │
└─────────────┘         tool calls / JSON          └──────────────────┘  REST     └──────────────────────┘

各 MCP ツールは、1 つの Quality Screener REST エンドポイントに対応しています。サーバーは、呼び出し元のベアラートークンをすべての送信リクエストに付加し（ヘッダーは X-Stobot-CLI-Token、または Authorization: Bearer … も使用可能）、デコードした JSON を返します。サーバー自体にビジネスロジックはなく、型付けされた認証付きの API ファサードです。

トランスポートモードは 2 種類あります。

トランスポート	用途	認証
stdio（デフォルト）	ローカルエージェント（例：Claude Code）がサーバーをサブプロセスとして起動します	$QSCREENER_TOKEN または ~/.config/qscreener/credentials.json のトークン
streamable-http	リモートからアクセス可能な外部デプロイメント（例：Railway）	エンドツーエンドの MCP OAuth 2.0。クライアントが最初にブラウザーを開き、その後はトークンを自動送信します。または、リクエストごとの X-Stobot-CLI-Token ヘッダーを使用します

HTTP 経由では、MCP エンドポイントは /mcp で提供されます。

---

クイックスタート（リモート）

サーバーを使う最も簡単な方法は、ホストされたデプロイメントを MCP クライアントに指定することです。コピーするトークンは不要です。初回接続時にクライアントがブラウザーでのサインインを開始します。

{
  "mcpServers": {
    "qscreener": {
      "type": "streamable-http",
      "url": "https://mcp.qualityscreener.io/mcp"
    }
  }
}

初回使用時に、ブラウザーで Quality Screener のサインインページが開きます。一度承認すれば、エージェントは接続されたままになります。Quality Screener のアカウントが必要です。エージェントには、ユーザー自身とまったく同じアクセス権が付与されます。

---

ローカルでの実行

uv が必要です。

# Install dependencies
uv sync

# stdio — for a local agent that launches this as a subprocess
uv run qscreener-mcp

# streamable-HTTP — mirrors the remote deployment
QSCREENER_MCP_TRANSPORT=streamable-http QSCREENER_MCP_PORT=8080 \
  QSCREENER_API_URL=http://localhost:8001 \
  uv run qscreener-mcp
# -> MCP endpoint at http://localhost:8080/mcp

Docker を使用する場合：

docker build -t qscreener-mcp .
docker run --rm -p 8080:8080 \
  -e QSCREENER_API_URL=https://your-backend.example.com \
  -e QSCREENER_MCP_PUBLIC_URL=http://localhost:8080 \
  qscreener-mcp
# -> MCP endpoint at http://localhost:8080/mcp

デフォルトでは、コンテナはポート 8080 で streamable-http トランスポートを実行します。

---

設定

すべての設定は環境変数で行い、起動時に解決されます。

環境変数	デフォルト値	説明
QSCREENER_API_URL	http://localhost:8001	ツールが呼び出す Quality Screener バックエンド API のベース URL
QSCREENER_MCP_TRANSPORT	stdio	stdio、streamable-http、または sse
QSCREENER_WEBSITE_URL	http://localhost:3001	OAuth ブラウザーログインリンクと共有可能なスクリーニング URL の生成に使用する Web アプリのベース URL
QSCREENER_MCP_PUBLIC_URL	http://localhost:{PORT|8080} (or https://$VERCEL_URL on Vercel)	このサーバーに外部からアクセスできるベース URL。OAuth の発行者 URL とコールバック URL として使用されます
QSCREENER_OAUTH_SIGNING_KEY	—	署名付き OAuth 状態、認可コード、クライアント登録用の HMAC キー。Vercel では必須です。単一の長時間稼働プロセスでは任意です
PORT	—	HTTP トランスポートのバインドポート（Railway によって自動設定されます）
QSCREENER_MCP_PORT	8080	PORT が未設定の場合に使用するバインドポートの代替値
QSCREENER_MCP_HOST	0.0.0.0	HTTP トランスポートのバインドホスト
QSCREENER_TOKEN	—	stdio モードのベアラートークンの上書き値（単一ユーザー向け）
QSCREENER_CONFIG_DIR	~/.config/qscreener	stdio モード用の credentials.json を格納するディレクトリ

---

認証

サーバーは各呼び出しで、次の優先順位に従ってベアラートークンを解決します。

1. HTTP リクエストヘッダー — X-Stobot-CLI-Token、次に Authorization: Bearer <token>。
2. $QSCREENER_TOKEN 環境変数。
3. $QSCREENER_CONFIG_DIR/credentials.json — token フィールド。

リモート（OAuth 2.0）

streamable-http でデプロイする場合、認証は MCP OAuth フローによって完全に自動化されます。

1. MCP クライアントが認可サーバーを検出し、ユーザーのブラウザーを開きます。
2. ブラウザーで Quality Screener Web アプリが表示され、ユーザーの Web セッションを有効期間の短い CLI トークンと交換して、このサーバーの /oauth/callback にリダイレクトします。
3. サーバーがトークンを MCP クライアントに渡し、MCP クライアントは以降のすべてのリクエストでそのトークンをベアラートークンとして送信します。

トークンは、バックエンドの /v1/cli/auth/whoami エンドポイントを呼び出してリクエストごとに検証されるため、取り消されたトークンや期限切れのトークンは直ちに拒否されます。サーバーはユーザートークンを永続化しません。アクセストークンは CLI トークンそのものなので、ローカルストアは不要です。QSCREENER_OAUTH_SIGNING_KEY が設定されている場合、保留中のログイン状態、認可コード、動的に登録されたクライアントは HMAC 署名付き JWT になります。これは Vercel のようなマルチインスタンスホストで必要です。キーを設定しない単一プロセスでは、従来どおりメモリー内で処理されます。

ローカル（stdio）

ブラウザーログインフローでトークンを発行してローカルに保存し、その後サーバーを stdio で実行します。

qscreener auth login                          # opens the web app, stores a token
cat ~/.config/qscreener/credentials.json      # the "token" field is your bearer token

または、CI やスクリプトでの使用には QSCREENER_TOKEN を直接設定します。

---

ツール

すべてのツールで認証が必要です。フィルター内では OR ロジック、フィルター間では AND ロジック が使用されます。時価総額は常に USD 建てです。

アカウントとステータス

ツール	シグネチャ	説明
auth_status	auth_status()	トークンが存在するかどうかと、そのトークンで認証されるユーザーを表示します。
account_profile	account_profile()	サインイン中のユーザーのプロフィール（メールアドレス、ユーザー名、組織）。
health	health()	API とデータベースのヘルスチェック。

スコアとスクリーニング

ツール	シグネチャ	説明
scores_top	scores_top(limit=20)	品質スコア上位のティッカーを、{ticker: score} マップとして返します。
scores_list	scores_list(ticker=None, sectors=None, industries=None, countries=None, currencies=None, exchanges=None, min_score=None, max_score=None, min_market_cap_usd=None, max_market_cap_usd=None, sort_by="quality_score", sort_order="desc", offset=0, limit=50, include_duplicates=False)	オプションのフィルターを指定して、スコア付きティッカーの一覧を返します。
scores_show	scores_show(ticker)	1つのティッカーのスコア行をすべて返します。
scores_for_tickers	scores_for_tickers(tickers, scoring_system_id=None)	デフォルトのスコアリング、または保存済みのスコアリングシステムに基づいて、指定したティッカーの現在のスコアを返します。不明なティッカーは除外されます。
scores_statistics	scores_statistics(sectors=None, min_score=None, max_score=None, min_market_cap_usd=None, max_market_cap_usd=None)	フィルターで絞り込んだ対象全体の最小・最大・平均スコアの統計を返します。
scores_market_cap	scores_market_cap(sectors=None, min_score=None)	フィルターで絞り込んだ対象全体の時価総額（USD）の合計を返します。
score_compute	score_compute(config, scoring_universe=None, sectors=None, industries=None, regions=None, countries=None, currencies=None, exchanges=None, min_market_cap_usd=None, max_market_cap_usd=None, sort_by="quality_score", sort_order="desc", offset=0, limit=50, include_duplicates=False)	CustomScoreConfig からカスタムスコアを計算します。scoring_universe は比較対象グループを選択し（スコアが変わります）、その他のフィルターは対象行を選択します（スコアは変わりません）。

共有

ツール	シグネチャ	説明
screen_share	screen_share(config)	CustomScoreConfig を保存し、公開用のコピー＆ペースト可能な共有リンク（url、slug、created、view_count）を返します。コンテンツアドレス方式のため、同一の設定には同じリンクが返されます。

フィルターとティッカー

ツール	シグネチャ	説明
filters_list	filters_list()	利用可能なフィルター値（セクター、業種、国、通貨、取引所）を返します。
tickers_list	tickers_list(limit=None)	利用可能なティッカーを返します。limit を指定すると、件数を制限できます。
tickers_search	tickers_search(query)	大文字と小文字を区別せず、部分一致で利用可能なティッカーを検索します。

スコア履歴

日付の形式は YYYY-MM-DD です。デフォルトの品質スコアの代わりに、保存済みのスコアリングシステムで履歴を計算するには、scoring_system_id を指定してください。

ツール	シグネチャ	説明
history_ticker	history_ticker(ticker, start=None, end=None, scoring_system_id=None)	指定した期間における1つのティッカーのスコア履歴を返します。
history_batch	history_batch(tickers, start=None, end=None, scoring_system_id=None)	複数のティッカーのスコア履歴を一度に返します。
history_top	history_top(top=10, scoring_system_id=None)	現在の上位N件のティッカーを取得し、それらのスコア履歴を返します。

保存済みのスコアリングシステム

スコアリングシステムは、アカウントに保存される、名前付きで再利用可能な CustomScoreConfig です。

ツール	シグネチャ	説明
systems_list	systems_list()	保存済みのスコアリングシステムの一覧を返します。
systems_show	systems_show(system_id)	IDで指定した保存済みのスコアリングシステムを表示します。
systems_create	systems_create(name, config, description=None)	設定オブジェクトからスコアリングシステムを作成します。
systems_update	systems_update(system_id, name=None, config=None, description=None)	保存済みのスコアリングシステムを更新します。
systems_delete	systems_delete(system_id)	保存済みのスコアリングシステムを削除します。
systems_apply	systems_apply(system_id)	保存済みのスコアリングシステムを適用します（使用回数が増加します）。

---

CustomScoreConfig を使用する

score_compute、screen_share、および systems_* ツールは、財務指標の重み付け方法を記述する CustomScoreConfig オブジェクトを受け付けます。その形式は Web ダッシュボードのスコアビルダーに対応しており、重み付きのグループと、各グループに含まれる重み付きの指標に加え、スコアリングパラメーターと任意のネストされた filters ブロックで構成されます。最小限の例を示します。

{
  "name": "My quality screen",
  "winsorizePercentile": 5,
  "missingDataPercentile": 0.25,
  "normalizeGroupZScores": false,
  "includeDuplicatesInScoring": false,
  "groups": [
    {
      "id": "returns",
      "name": "Returns",
      "weight": 0.5,
      "metrics": [
        { "id": "roe", "name": "ROE", "weight": 0.5 },
        { "id": "roic", "name": "ROIC", "weight": 0.5 }
      ]
    },
    {
      "id": "profitability",
      "name": "Profitability",
      "weight": 0.5,
      "metrics": [
        { "id": "profit_margin", "name": "Profit Margin", "weight": 1.0 }
      ]
    }
  ],
  "scoringUniverseFilters": { "countries": ["Italy"], "min_market_cap": 1 },
  "filters": { "min_score": 1.2 }
}

スコアリングパラメーターではキャメルケースを使用します。winsorizePercentile（1～10）、missingDataPercentile（0.1～0.5）、normalizeGroupZScores、includeDuplicatesInScoring（ブール値）です。scoringUniverseFilters はスコアを計算する対象のピアグループを定義し、ネストされた filters ブロックには保存済みスクリーンの状態を格納します。両ブロック内の時価総額は10 億米ドル単位です（ツールの引数では米ドル単位です）。スネークケースのキー、従来の winsorize／zScore フラグ、最上位に置かれたフィルターキーなど、形式の緩い入力は自動的にこの形式に正規化されますが、最初からこの形式で出力することを推奨します。有効なフィルター値を確認するには filters_list を使用してください。また、コピー元となる設定を用意したい場合は、ダッシュボードで設定を対話的に作成してください。

2 つの段階：スコアの比較対象を決めてから、絞り込む

クオリティスコアは相対評価です。各企業は母集団に対してウィンズライジングされ、Z スコア化されます。そのため、どの企業をピアグループに含めるかとどの行を見るかは別の問題であり、score_compute ではそれぞれを個別に指定します。

段階	指定場所	効果
1. スコアリング対象ユニバース	scoring_universe 引数、または config.scoringUniverseFilters	ウィンズライジング／Z スコア化の前に適用されます — すべてのスコアが変わります
2. 結果フィルター	sectors／countries／… 引数	スコアリングの後に適用されます — スコアは変わりません

「欧州のテック企業を、欧州のテック企業を基準に評価した上位企業」と「欧州のテック企業を、世界全体を基準に評価した上位企業」は、同じリストを再スケーリングしたものではなく、別のリストです。ユニバースを絞ると、指標ごとに境界値、平均値、σが異なる幅で動くため、企業の順位も実際に入れ替わります。

// judged against European tech — the peer group is European tech
score_compute(config, scoring_universe={"sectors": ["Technology"], "regions": ["Europe"]})

// judged against the world — the peer group is everyone, then Europe is shown
score_compute(config, sectors=["Technology"], regions=["Europe"])

段階 1 では sectors、industries、regions、countries、currencies、exchanges、min_market_cap_usd、max_market_cap_usd を受け付けます。min_score、max_score、ticker、tickers は無視されず、エラーになります。最初の 2 つは計算対象のスコア自体でフィルターするもの、残りは行を選択するものだからです。

すべてのレスポンスには、ピアグループとその規模を示す scoring_universe フィールドが含まれます。異なるピアグループに対して計算したスコアは比較できないため、同じ表に混在させないでください。

知っておくべき注意点が 2 つあります。

• 段階 2 の引数として指定した min_market_cap_usd も、スコアリング対象の母集団に下限を設けます。 これは互換性のために維持されている、以前からのバックエンドの動作です。ピアグループを明示的に制御するには、scoring_universe 内に min_market_cap_usd を設定してください。これにより段階 2 の下限が上書きされます。max_market_cap_usd は、scoring_universe に設定しない限り行だけをフィルターします。
• ユニバースが非常に小さくてもスコアは計算されます。 現時点では母集団の最小規模をチェックするガードがないため、企業が十数社しかない場合に 5／95 パーセンタイルでウィンズライジングすると、確信に満ちた無意味な結果が返されます。

ネストされた filters ブロックの役割

これは保存済みスクリーンの状態です。screen_share と systems_create／systems_update はこれを保存するため、共有スクリーンや保存済みスコアリングシステムをダッシュボードで再度開いたときに、選択したフィルターが復元されます。

ピアグループは定義しません。ピアグループを定義するのは scoringUniverseFilters です。保存済み設定を score_compute に渡すと、その filters ブロックが段階 2のフィルターとして適用されます（明示的に渡した引数が優先されます）。これはダッシュボードの動作と一致するため、保存済みシステムを再スコアリングしても表示内容が維持されます。

---

MCP クライアントの接続

リモート（推奨）

streamable-http に対応した MCP クライアントであれば使用できます。OAuth によってログインするため、トークンは不要です。

{
  "mcpServers": {
    "qscreener": {
      "type": "streamable-http",
      "url": "https://mcp.qualityscreener.io/mcp"
    }
  }
}

クライアントが OAuth フローを実行できない場合は、発行済みのトークンを直接送信してください。

{
  "mcpServers": {
    "qscreener": {
      "url": "https://mcp.qualityscreener.io/mcp",
      "headers": { "X-Stobot-CLI-Token": "<your token>" }
    }
  }
}

ローカル（stdio）

{
  "mcpServers": {
    "qscreener": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/quality-screener-mcp-server", "qscreener-mcp"],
      "env": { "QSCREENER_API_URL": "https://your-backend.example.com" }
    }
  }
}

---

デプロイ

サーバーは単一のコンテナとしてデプロイされます。Railway では次の手順で行います。

1. 新しいサービス → リポジトリからデプロイを選択し、このリポジトリを指定します。Dockerfile は自己完結型のため、ビルドコンテキストはリポジトリのルートです。

2. 環境変数を設定します。

   • QSCREENER_MCP_TRANSPORT=streamable-http
   • QSCREENER_API_URL=https://<your-backend-domain>
   • QSCREENER_WEBSITE_URL=https://<your-frontend-domain>
   • QSCREENER_MCP_PUBLIC_URL=https://<generated-mcp-domain>

   Railway は PORT を自動的に設定し、サーバーはそのポートで待ち受けます。

3. ネットワーク → ドメインを生成を選択します。MCP エンドポイントは https://<generated-domain>/mcp です。

   • HTTP ヘルスチェックのパスは未設定のままにするか、TCP チェックを使用します。/mcp は単純な GET に対して 406 Not Acceptable を返すため、200 を想定する HTTP ヘルスチェックではデプロイが異常と判定されます。

4. MCP クライアントを接続します。初回接続時に OAuth フローが自動的に開始されます。

---

Vercel へのデプロイ

Docker／Railway で mcp.run() を介して提供されるものと同じ ASGI アプリが、app.py から FastAPI の app としてエクスポートされるため、Vercel の Python ランタイムで 1 つの Function としてホストできます。FastMCP アプリはすでに /mcp、/.well-known/*、/authorize、/token、/register、/oauth/callback で待ち受けます。Vercel は元のパスを維持したまま、すべてのリクエストをこの Function にルーティングするため、パスの再マッピングなしで各 URL が解決されます。vercel.json は app.py に maxDuration（60s）を設定するだけです。

/mcp（または OAuth のパス）を / に書き換えないでください。FastMCP はパスを文字どおりに照合します。

このリポジトリを指定して Vercel プロジェクトを作成します（Framework Preset：FastAPI／Other、Root Directory：リポジトリのルート）。次の環境変数を設定します。値ではなく、変数名のみを設定してください。値をコミットしないでください。

環境変数	必須	用途
QSCREENER_API_URL	はい	ツールが呼び出す Quality Screener バックエンドのベース URL
QSCREENER_WEBSITE_URL	はい	OAuth のブラウザーログインと共有可能なスクリーニングリンクに使用するウェブアプリのオリジン
QSCREENER_MCP_PUBLIC_URL	カスタムドメインでは必須	このデプロイのパブリックオリジン（OAuth 発行者＋/oauth/callback）。プレビューデプロイでは省略でき、その場合は https://$VERCEL_URL が使用されます
QSCREENER_OAUTH_SIGNING_KEY	はい	OAuth の保留中状態、認可コード、動的クライアント登録に署名し、それらを Function の呼び出し間で維持するための HMAC シークレットです。長いランダム文字列（32 バイト以上）を使用してください

Vercel は VERCEL_URL を自動的に設定します（スキームなしのホスト名）。QSCREENER_MCP_PUBLIC_URL が未設定の場合に限り、発行者 URL のフォールバックとして使用されます。MCP クライアントがカスタムドメイン経由で接続する場合、本番環境の発行者 URL として使用しないでください。

Vercel では、次の環境変数は不要です（app.py のエントリーポイントは常に HTTP であり、Function はポートにバインドしません）。

• QSCREENER_MCP_TRANSPORT
• QSCREENER_MCP_HOST
• QSCREENER_MCP_PORT / PORT
• QSCREENER_TOKEN
• QSCREENER_CONFIG_DIR

デプロイ後の MCP エンドポイントは https://<vercel-domain>/mcp です。Railway のデプロイと同じ方法で、その URL を MCP クライアントに指定してください。カスタムスコアリングが 60s の上限に達する場合は、vercel.json の functions["app.py"].maxDuration を増やしてください。

---

開発

uv sync            # install dependencies (including dev)
uv run pytest      # run the test suite

コードベースは小規模で、自己完結しています。

パス	用途
qscreener_mcp/server.py	FastMCP サーバー、ツール定義、トランスポートのエントリーポイント
qscreener_mcp/client.py	Bearer トークンを付与する最小限の httpx クライアント
qscreener_mcp/oauth.py	MCP OAuth 2.0 プロバイダー（トークン検証、ブラウザーフロー）
app.py	ストリーミング可能な HTTP ASGI アプリをマウントする Vercel FastAPI エントリーポイント
tests/	pytest テストスイート（トークン解決、フィルター転送、共有リンク生成）

---

プライバシーポリシー

プライバシーポリシーの全文は PRIVACY.md (https://github.com/quality-screener/quality-screener-mcp-server/blob/main/PRIVACY.md) で公開されています。

要約すると、次のとおりです。

• 保持される個人データは、アカウントを特定する メールアドレス のみです。ユーザー名と組織名は任意のプロフィール項目です。
• MCP サーバーは ステートレスなプロキシ です。データベースを持たず、独自のストレージに個人データを書き込みません。各リクエストは、共有アカウントではなく、お客様の アクセストークンを使用して Quality Screener API に転送されます。
• お客様のデータが 販売されることはなく、広告にも機械学習モデルのトレーニングにも使用されません。
• 運用ログでは、アカウントをメールアドレスではなく仮名化されたユーザー ID で参照します。
• アカウントを削除すると、アカウントデータも削除されます。

保持期間、第三者への提供先、国際移転、および GDPR に基づく権利については、ポリシーをご確認ください。

---

サポート

チャネル	用途
[email protected]	サポートの依頼、セキュリティ報告、プライバシーおよびデータ主体に関する依頼
GitHub Issues	バグ報告と機能リクエスト

この README は MCP サーバーの正式なドキュメントです。 https://github.com/quality-screener/quality-screener-mcp-server

セキュリティ上の脆弱性が疑われる場合は、公開 Issue を作成せず、メールで非公開に報告してください。

---

ライセンス

MIT © Quality Screener.