Quality Screener MCP Server
Use this MCP server to act as a signed-in Quality Screener user and screen, score, analyze, share, and manage stock-screening data through REST-backed tools.
Check authentication status, account profile, and API/database health.
List, filter, sort, and inspect scored tickers; get score statistics and aggregate market cap.
Compute custom quality scores from weighted metric configs, against a chosen scoring universe, with separate result filters.
Create public, content-addressed share links for screen configurations.
Discover available filter values and tickers, and search tickers by substring.
Retrieve score history for individual tickers, batches of tickers, or current top-N tickers.
List, view, create, update, delete, and apply saved scoring systems.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Quality Screener MCP Server screen for stocks with quality score above 80"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Quality Screener MCP server
A standalone Model Context Protocol (MCP) server that exposes the Quality Screener stock-screening engine as tools for AI agents (Claude, Cursor, and any other MCP client).
Once connected, an agent can screen and filter the scored universe, compute custom quality scores, inspect score history, manage saved scoring systems, and generate shareable screen links — acting as the signed-in user, against the same data they see in the web dashboard.
No SDK dependency. The server is a thin HTTP layer over the public Quality Screener API. It has no dependency on the backend Python package — every tool just calls a REST endpoint and returns the JSON payload.
Multi-tenant & credential-free. When deployed over HTTP the server stores no credentials of its own. Each request carries the caller's own access token, which the server forwards to the API, so a single public deployment can serve many users without ever acting on a shared account.
Table of contents
Related MCP server: Rozkoduj MCP
How it works
┌─────────────┐ MCP (stdio | streamable-HTTP) ┌──────────────────┐ HTTPS ┌──────────────────────┐
│ AI agent │ ────────────────────────────────► │ qscreener-mcp │ ────────► │ Quality Screener API │
│ (MCP client)│ ◄──────────────────────────────── │ (this server) │ ◄──────── │ (FastAPI backend) │
└─────────────┘ tool calls / JSON └──────────────────┘ REST └──────────────────────┘Each MCP tool maps to one Quality Screener REST endpoint. The server attaches
the caller's bearer token to every outbound request (header
X-Stobot-CLI-Token, Authorization: Bearer … also accepted) and returns the
decoded JSON. There is no business logic in the server itself — it is a typed,
authenticated façade over the API.
It runs in two transport modes:
Transport | Use | Authentication |
| A local agent (e.g. Claude Code) launches the server as a subprocess | Token from |
| A remote, externally reachable deployment (e.g. Railway) | End-to-end MCP OAuth 2.0 — the client opens the browser once, then sends the token automatically; or a per-request |
Over HTTP the MCP endpoint is served at /mcp.
Quick start (remote)
The easiest way to use the server is to point your MCP client at the hosted deployment. No token to copy — the client triggers a browser sign-in on first connect:
{
"mcpServers": {
"qscreener": {
"type": "streamable-http",
"url": "https://mcp.qualityscreener.io/mcp"
}
}
}On first use your browser opens the Quality Screener sign-in page. Approve once, and the agent stays connected. You need a Quality Screener account; the agent inherits exactly your access.
Running locally
Requires 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/mcpWith 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/mcpBy default the container runs the streamable-http transport on port 8080.
Configuration
All configuration is via environment variables, resolved at startup.
Env var | Default | Meaning |
|
| Base URL of the Quality Screener backend API the tools call |
|
|
|
|
| Web-app base URL used to build the OAuth browser-login link and shareable screen URLs |
|
| Publicly reachable base URL of this server; used as the OAuth issuer and callback URL |
| — | HMAC key for signed OAuth state, authorization codes, and client registrations. Required on Vercel; optional on a single long-lived process |
| — | Bind port for HTTP transports (Railway sets this automatically) |
|
| Bind port fallback when |
|
| Bind host for HTTP transports |
| — | Bearer-token override for stdio mode (single user) |
|
| Directory holding |
Authentication
The server resolves a bearer token for each call with the following precedence:
HTTP request header —
X-Stobot-CLI-Token, thenAuthorization: Bearer <token>.$QSCREENER_TOKENenvironment variable.$QSCREENER_CONFIG_DIR/credentials.json— thetokenfield.
Remote (OAuth 2.0)
For a streamable-http deployment, authentication is fully automated via the
MCP OAuth flow:
The MCP client discovers the authorization server and opens the user's browser.
The browser lands on the Quality Screener web app, which exchanges the user's web session for a short-lived CLI token and redirects back to this server's
/oauth/callback.The server hands the token to the MCP client, which sends it as a bearer token on every subsequent request.
The token is validated on each request by calling the backend's
/v1/cli/auth/whoami endpoint, so a revoked or expired token is rejected
immediately. The server never persists user tokens. Access tokens are the
CLI token, so they need no local store. Pending login state, authorization
codes, and dynamically registered clients are HMAC-signed JWTs when
QSCREENER_OAUTH_SIGNING_KEY is set, which is what a multi-instance host
(Vercel) needs; a single process without the key keeps the original
in-memory behaviour.
Local (stdio)
Mint a token through the browser login flow and store it locally, then run the server over stdio:
qscreener auth login # opens the web app, stores a token
cat ~/.config/qscreener/credentials.json # the "token" field is your bearer tokenOr set QSCREENER_TOKEN directly for CI / scripted use.
Tools
All tools require authentication. Filters use OR logic within a filter and AND logic across filters. Market caps are always in USD.
Account & status
Tool | Signature | Description |
|
| Whether a token is present and which user it authenticates as. |
|
| The signed-in user's profile (email, username, organization). |
|
| API and database health check. |
Scores & screening
Tool | Signature | Description |
|
| Top tickers by quality score, as a |
|
| List scored tickers with optional filters. |
|
| Full score row(s) for a single ticker. |
|
| Current scores for a specific list of tickers, under default scoring or a saved scoring system. Unknown tickers are omitted. |
|
| Min / max / average score statistics for a filtered universe. |
|
| Aggregated total market cap (USD) for a filtered universe. |
|
| Compute custom scores from a |
Sharing
Tool | Signature | Description |
|
| Persist a |
Filters & tickers
Tool | Signature | Description |
|
| Available filter values (sectors, industries, countries, currencies, exchanges). |
|
| Available tickers, optionally truncated to |
|
| Search available tickers by case-insensitive substring. |
Score history
Dates are YYYY-MM-DD. Pass scoring_system_id to compute history against a
saved scoring system instead of the default quality score.
Tool | Signature | Description |
|
| Score history for a single ticker over a date range. |
|
| Score history for several tickers at once. |
|
| Fetch the current top-N tickers and return their score history. |
Saved scoring systems
A scoring system is a named, reusable CustomScoreConfig stored against your
account.
Tool | Signature | Description |
|
| List your saved scoring systems. |
|
| Show a saved scoring system by ID. |
|
| Create a saved scoring system from a config object. |
|
| Update a saved scoring system. |
|
| Delete a saved scoring system. |
|
| Apply a saved scoring system (increments its usage count). |
Working with CustomScoreConfig
score_compute, screen_share, and the systems_* tools accept a
CustomScoreConfig object describing how to weight financial metrics. Its shape
mirrors the score builder in the web dashboard: weighted metric groups, each
containing weighted metrics, plus scoring parameters and an optional nested
filters block. A minimal example:
{
"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 }
}Scoring parameters use camelCase: winsorizePercentile (1-10), missingDataPercentile
(0.1-0.5), normalizeGroupZScores and includeDuplicatesInScoring (booleans).
scoringUniverseFilters defines the peer group the scores are computed against; the nested
filters block holds saved-screen state. Market caps are in billions USD inside both
blocks (the tool arguments take USD). Loose inputs — snake_case keys, the legacy
winsorize/zScore flags, or filter keys placed at the top level — are normalized to this
shape automatically, but emitting it directly is preferred. Use filters_list to discover valid filter values, and build a config
interactively in the dashboard if you want a starting point to copy.
Two stages: score against, then filter
Quality scores are relative — every company is winsorized and z-scored against a
population — so who is in the peer group and which rows you look at are different
questions, and score_compute takes them separately.
Stage | Where | Effect |
1. Scoring universe |
| applied before winsorize/z-score — changes every score |
2. Result filters | the | applied after scoring — never changes a score |
"Best European tech judged against European tech" and "best European tech judged against the world" are different lists, not the same list rescaled — narrowing the universe moves each metric's bounds, mean and σ by different amounts, so companies genuinely reorder:
// 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"])Stage 1 accepts sectors, industries, regions, countries, currencies, exchanges,
min_market_cap_usd and max_market_cap_usd. It rejects min_score, max_score, ticker
and tickers with an error rather than ignoring them: the first two filter on the very
scores being computed, the rest select rows.
Every response carries a scoring_universe field naming the peer group and its size. Scores
computed against different peer groups are not comparable — do not mix them in one table.
Two edges worth knowing:
min_market_cap_usdas a stage-2 argument also floors the scoring population. This is long-standing backend behaviour, kept for compatibility. Setmin_market_cap_usdinsidescoring_universeto control the peer group explicitly; it overrides the stage-2 floor.max_market_cap_usdfilters rows only unless you set it inscoring_universe.A very small universe still scores. There is no minimum-population guard yet, so winsorizing at the 5th/95th percentile of a dozen companies returns confident nonsense.
What the nested filters block does
It is saved-screen state. screen_share and systems_create/systems_update persist
it so a shared screen or saved scoring system restores its filter selections when reopened
in the dashboard.
It does not define the peer group — scoringUniverseFilters does. Passing a saved config to
score_compute applies its filters block as stage-2 filters (an explicit argument
wins), matching what the dashboard does, so re-scoring a saved system keeps its view.
Connecting an MCP client
Remote (recommended)
Any streamable-http MCP client works. No token needed — OAuth handles login:
{
"mcpServers": {
"qscreener": {
"type": "streamable-http",
"url": "https://mcp.qualityscreener.io/mcp"
}
}
}If your client cannot perform the OAuth flow, send a minted token directly:
{
"mcpServers": {
"qscreener": {
"url": "https://mcp.qualityscreener.io/mcp",
"headers": { "X-Stobot-CLI-Token": "<your token>" }
}
}
}Local (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" }
}
}
}Deployment
The server deploys as a single container. On Railway:
New service → Deploy from repo, pointing at this repository. The Dockerfile is self-contained, so the build context is the repo root.
Set environment variables:
QSCREENER_MCP_TRANSPORT=streamable-httpQSCREENER_API_URL=https://<your-backend-domain>QSCREENER_WEBSITE_URL=https://<your-frontend-domain>QSCREENER_MCP_PUBLIC_URL=https://<generated-mcp-domain>
Railway injects
PORTautomatically; the server binds to it.Networking → Generate Domain. The MCP endpoint is
https://<generated-domain>/mcp.Leave the HTTP healthcheck path unset (or use a TCP check):
/mcpanswers406 Not Acceptableto a plainGET, so an HTTP healthcheck expecting200would mark the deploy unhealthy.
Connect your MCP client — the OAuth flow triggers automatically on first connection.
Deploy on Vercel
The same ASGI app that Docker/Railway serve via mcp.run() is exported from
app.py as a FastAPI app so Vercel’s Python runtime can host it as one
Function. The FastMCP app already listens on /mcp, /.well-known/*,
/authorize, /token, /register, and /oauth/callback; Vercel routes
every request to that Function with the original path, so those URLs resolve
without remapping. vercel.json only sets maxDuration (60s) on app.py.
Do not rewrite /mcp (or the OAuth paths) onto / — FastMCP matches the
literal paths.
Create a Vercel project pointed at this repository (Framework Preset: FastAPI / Other, Root Directory: repository root). Set these environment variables — names only; never commit values:
Env var | Required | What it is for |
| yes | Base URL of the Quality Screener backend the tools call |
| yes | Web-app origin used for the OAuth browser login and shareable screen links |
| yes on a custom domain | Public origin of this deployment (OAuth issuer + |
| yes | HMAC secret used to sign OAuth pending-state, authorization codes, and dynamic client registrations so they survive across Function invocations. Use a long random string (32+ bytes) |
Vercel injects VERCEL_URL automatically (hostname, no scheme). It is only a
fallback issuer when QSCREENER_MCP_PUBLIC_URL is unset. Do not use it as
the production issuer if the MCP client will connect via a custom domain.
These are not required on Vercel (the app.py entrypoint is always HTTP,
and the Function does not bind a port):
QSCREENER_MCP_TRANSPORTQSCREENER_MCP_HOSTQSCREENER_MCP_PORT/PORTQSCREENER_TOKENQSCREENER_CONFIG_DIR
After deploy the MCP endpoint is https://<vercel-domain>/mcp. Point an MCP
client at that URL the same way as the Railway deployment. Raise
functions["app.py"].maxDuration in vercel.json if custom scoring hits the
60s cap.
Development
uv sync # install dependencies (including dev)
uv run pytest # run the test suiteThe codebase is small and self-contained:
Path | Purpose |
| FastMCP server, tool definitions, transport entry point |
| Minimal httpx client that attaches the bearer token |
| MCP OAuth 2.0 provider (token validation, browser flow) |
| Vercel FastAPI entrypoint that mounts the streamable-HTTP ASGI app |
| pytest suite (token resolution, filter forwarding, share-link building) |
Privacy Policy
The full privacy policy is published at PRIVACY.md (https://github.com/quality-screener/quality-screener-mcp-server/blob/main/PRIVACY.md).
In short:
The only personal data retained is your email address, which identifies your account. Username and organization are optional profile fields.
The MCP server is a stateless proxy — it holds no database and writes no personal data to storage of its own. Each request is forwarded to the Quality Screener API using your access token, never a shared account.
Your data is not sold, not used for advertising, and not used to train machine-learning models.
Operational logs reference accounts by a pseudonymous user ID, not by email.
Account data is deleted when you delete your account.
See the policy for retention periods, third-party recipients, international transfers, and your GDPR rights.
Support
Channel | Use it for |
Support requests, security reports, privacy and data-subject requests | |
Bug reports and feature requests |
This README is the canonical documentation for the MCP server: https://github.com/quality-screener/quality-screener-mcp-server
Please report suspected security vulnerabilities privately by email rather than opening a public issue.
License
MIT © Quality Screener.
Available Tools
23 toolsaccount_profileARead-onlyInspect
Return the signed-in user's profile (email, username, organization).
Inputs: no named parameters.
auth_statusARead-onlyInspect
Report whether a CLI token is present and which user it authenticates as.
Inputs: no named parameters.
filters_listARead-onlyInspect
Return available filter values (sectors, industries, countries, currencies, exchanges).
Inputs: no named parameters.
history_batchARead-onlyInspect
Return score history for several tickers at once.
Inputs: tickers (required), end, start, scoring_system_id.
history_tickerARead-onlyInspect
Return score history for a single ticker (dates: YYYY-MM-DD).
Inputs: ticker (required), end, start, scoring_system_id.
history_topBRead-onlyInspect
Fetch the top-N tickers and return their score history.
Inputs: top, scoring_system_id.
score_computeARead-onlyInspect
Compute custom scores from a CustomScoreConfig, scored against a chosen peer group.
The config is a CustomScoreConfig: weighted metric groups (each with weighted
metrics) plus scoring parameters winsorizePercentile (1-10), missingDataPercentile
(0.1-0.5), normalizeGroupZScores and includeDuplicatesInScoring (booleans). Loose
inputs (snake_case keys, legacy winsorize/zScore flags) are normalized automatically.
Scoring happens in two stages, and they answer different questions.
Stage 1 — scoring_universe: who is in the peer group. Quality scores are
relative: each company is winsorized and z-scored against a population. Narrowing this
changes every score and can reorder the list. Accepts sectors, industries,
regions, countries, currencies, exchanges, min_market_cap_usd and
max_market_cap_usd. Omit it to score against the whole universe.
Stage 2 — the filter arguments below: which rows come back. Applied after scoring, so they never change a score. They accept the same keys as stage 1, so any filter can be asked either way. OR logic within a filter, AND across filters.
So "best European tech judged against European tech" is
scoring_universe={"sectors": ["Technology"], "regions": ["Europe"]}, while "best
European tech judged against the world" is sectors=["Technology"], regions=[...] as
stage-2 arguments. The response's scoring_universe field reports the peer group and
its size — scores computed against different peer groups are not comparable, so do not
mix them in one table.
Two things do not fit the split cleanly, and both are deliberate:
min_market_cap_usdas a stage-2 argument also floors the scoring population (a long-standing backend behaviour). Setmin_market_cap_usdinsidescoring_universeto control the peer group explicitly; it overrides the stage-2 floor.max_market_cap_usdfilters rows only unless set inscoring_universe.min_score/max_score/ticker/tickerscannot appear inscoring_universe: the first two filter on the scores being computed, the rest select rows. Passing them there returns an error rather than being ignored.
A nested config['filters'] block is saved-screen state, persisted by
screen_share/systems_create/systems_update so a screen restores its view.
Passing a saved config here applies that block as stage-2 filters (an explicit argument
below wins), matching what the web app does — it never defines the peer group.
Inputs: config (required), limit, offset, regions, +11 more.
scores_for_tickersARead-onlyInspect
Return current scores for a specific list of tickers.
Looks up the latest score for each requested ticker under the default quality
score, or under a saved scoring system when scoring_system_id is given (which
requires being signed in and owning that system). Tickers with no score are
omitted from the response. Results are sorted by quality score descending.
Rows are slimmed for MCP by default (duplicates as ticker strings,
description truncated); pass full_rows=True for the raw backend payload.
Args: tickers: Exact ticker symbols to score (e.g. ["AAPL", "MSFT", "ASML.AS"]). scoring_system_id: Optional saved scoring-system id; omit for default scoring. full_rows: Return unmodified rows (embedded duplicate rows, full descriptions).
Returns:
dict: A ScoreListResponse with data (one row per found ticker),
pagination (total_count = number found), and aggregates.
Inputs: tickers (required), full_rows, scoring_system_id.
scores_listBRead-onlyInspect
List scored tickers with optional filters. Market caps are in USD.
Rows are slimmed for MCP by default (duplicates as ticker strings, description
truncated); pass full_rows=True for the raw backend payload.
Inputs: limit, offset, ticker, sectors, +12 more.
scores_market_capBRead-onlyInspect
Return aggregated total market cap (USD) for a filtered universe.
Inputs: sectors, min_score.
scores_showBRead-onlyInspect
Return the score row(s) for a single ticker.
Inputs: ticker (required).
scores_statisticsBRead-onlyInspect
Return min/max/average score statistics for a filtered universe.
Inputs: sectors, max_score, min_score, max_market_cap_usd, +1 more.
scores_topBRead-onlyInspect
Return the top tickers by quality score as a {ticker: score} map.
Inputs: limit.
systems_applyAInspect
Apply a saved scoring system (increments its usage count).
Inputs: system_id (required).
systems_createBInspect
Create a saved scoring system from a config object.
Inputs: name (required), config (required), description.
systems_deleteBDestructiveIdempotentInspect
Delete a saved scoring system.
Inputs: system_id (required).
systems_listARead-onlyInspect
List the user's saved scoring systems.
Inputs: no named parameters.
systems_showARead-onlyInspect
Show a saved scoring system by ID.
Inputs: system_id (required).
systems_updateCIdempotentInspect
Update a saved scoring system.
Inputs: system_id (required), name, config, description.
tickers_listARead-onlyInspect
Return available tickers, optionally truncated to limit.
Inputs: limit.
tickers_searchARead-onlyInspect
Search available tickers by case-insensitive substring.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools map to a distinct resource/action (scores queries, history, systems CRUD, tickers/filters), and the descriptions clearly separate custom score computation from canned score lookups. A few pairs overlap conceptually, such as scores_list vs scores_top or auth_status vs account_profile, but their output shapes and inputs make them distinguishable.
Tool names are predominantly snake_case and follow a resource-prefix pattern like scores_*, systems_*, history_*, and tickers_*. Minor deviations such as score_compute (singular vs the plural scores_* family), screen_share (noun_verb rather than resource_verb), and the non-action names auth_status/health keep it from being fully consistent.
At 23 tools the surface is heavy and falls in the borderline 16-25 range; some tools like scores_top, scores_for_tickers, and history_top overlap with list/batch operations and could be consolidated. The broad scope (auth, scores, screens, systems, history) justifies most of the count, but it is not tight.
Core workflows are well covered: score retrieval, custom score computation, saved-system CRUD, screen sharing, filters, tickers, history, and health/auth. Minor gaps exist, such as no way to fetch a shared screen by slug and no direct score-comparison tool, but agents can work around these without dead ends.
Maintenance
Related MCP Connectors
Equity screeners for 26 global markets as agent tools.
AI equity research: quant scores, fundamentals, valuation, risks and portfolio audits for any stock.
Stock valuations, fundamentals, bounded screens, and OAuth-enabled portfolio research.
Screen global stocks, options, ETFs and crypto in plain English, and set email alerts on any screen.
Related MCP Servers
- AlicenseBqualityCmaintenanceProvides comprehensive stock screening capabilities through Yahoo Finance. Enables LLMs to screen stocks based on technical, fundamental, and options criteria, with support for watchlist management and result storage.449MIT

Rozkoduj MCPofficial
AlicenseAqualityAmaintenanceProvides AI assistants with market screening, analysis, and scoring across stocks, crypto, and forex, enabling natural language queries for trading insights.4MIT- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to search, screen, and analyze 8,200+ NSE and BSE listed securities through 55 tools covering live quotes, financials, technical indicators, FII/DII flows, option chains, filings, IPOs, bulk deals, and portfolio P&L.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read cited stock news, earnings, and filings; screen stocks; run point-in-time backtests; check portfolios; and query a local dashboard across US, A-share, and Hong Kong markets.46 PyPI1MIT