market-research-mcp
A read-only market-research MCP server for public-company and macro data, with source URLs and dates on results.
Check server status/version with
ping.Resolve tickers or company names to SEC CIK, exchange and SIC industry code.
List SEC filings, filtered by form type and filing date.
Read paged plain text of 10-K/10-Q sections (e.g. Risk Factors, MD&A) and filing exhibits such as earnings-release EX-99.1.
Fetch SEC Form 4 insider transactions with transaction codes, open-market summaries and amendment handling.
Fetch SEC XBRL fundamentals, annual or quarterly, with the XBRL tag and filing provenance.
Fetch FRED macro series observations, units, frequency and last-updated metadata.
Get daily OHLCV/adjusted-close price history and descriptive price stats: returns, drawdown, 52-week range, volatility.
Get next earnings dates via Finnhub or an SEC-based estimate, clearly marked by method.
Results include source, source URL, retrieval date, notes and staleness flags; there are no recommendations, forecasts, ratings or trading actions.
The provided schema does not expose the README's
get_key_ratiostool.
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., "@market-research-mcp pull Apple's latest 10-K from SEC EDGAR and note the filing date"
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.
market-research-mcp
An MCP server with read-only research tools over public
market data: SEC EDGAR filings and XBRL fundamentals, FRED macro series, end-of-day prices and
earnings dates. It ships as a Claude Code plugin with an analyze-ticker skill.
Read-only by construction. There is no code that places, modifies or cancels orders or moves money. No broker connection.
Not financial advice. Tools return data with its source URL and date. Nothing produces buy/sell recommendations, ratings or price targets.
Bring your own keys. Keys are read from environment variables or a local
.envfile.
Requirements
uv. uv installs Python 3.12+ for you from
.python-version; no system Python needed.Git. Both the clone and the Claude Code plugin install fetch this repository with git.
Related MCP server: market-pulse
Keys
Variable | Required? | Where to get it | Free tier |
| Yes, for all SEC tools | No signup. Your name and email, e.g. | Free. Max 10 requests/second |
| For | Free. The terms publish no numeric limit; 120 requests/minute is commonly cited (UNVERIFIED) | |
| For price tools (default provider) | Starter: 50 requests/hour, 1,000/day, 500 unique symbols/month, internal (personal) use only (pricing) | |
| Optional, for announced earnings dates | About 60 calls/minute, earnings calendar included, personal use only (UNVERIFIED). Without a key, dates are estimated from past SEC filings and marked as estimates | |
| Optional |
| n/a |
| Optional | SQLite cache, default | n/a |
| Optional | Default | n/a |
| Optional | Briefs go to | n/a |
| Optional | Path of a | n/a |
Missing keys do not stop the server: a tool that needs a key returns an error naming it.
Where to put .env
Copy .env.example and fill it in. Settings are read in this order, first
wins:
Real environment variables.
The file named by
MRM_ENV_FILE, if set. Otherwise the per-user file:%APPDATA%\market-research-mcp\.envon Windows,~/.config/market-research-mcp/.envelsewhere ($XDG_CONFIG_HOMEis honoured)..envin the current working directory (for a clone, the repository root).
A .env inside the installed plugin folder is never read: plugin updates replace that folder.
.env is gitignored; never commit it.
Install as a Claude Code plugin
Install uv and create the per-user
.envabove with at leastSEC_USER_AGENT.In Claude Code:
/plugin marketplace add romanmoravskyi/market-research-mcp/plugin install market-research@market-research-mcp, then restart Claude Code or run/reload-plugins.Ask "analyze MSFT" or run
/market-research:analyze-ticker MSFT.
The plugin starts the MCP server with uv run and adds the analyze-ticker skill.
Use as a plain MCP server
Clone and install:
git clone https://github.com/romanmoravskyi/market-research-mcp.git
cd market-research-mcp
uv syncClaude Desktop (claude_desktop_config.json; use absolute paths):
{
"mcpServers": {
"market-research": {
"command": "uv",
"args": ["--directory", "/path/to/market-research-mcp", "run", "market-research-mcp"],
"env": { "MRM_ENV_FILE": "/path/to/your/.env" }
}
}
}Any stdio MCP client: launch uv --directory /path/to/market-research-mcp run market-research-mcp;
the server speaks MCP over stdin/stdout. In Claude Code without the plugin:
claude mcp add market-research -- uv --directory /path/to/market-research-mcp run market-research-mcpTools
Tool | What it returns |
| Server status and version |
| Company name, CIK, exchange and SIC code from SEC |
| SEC filings for a ticker, filtered by form and date |
| Text of one 10-K/10-Q item (e.g. 1A risk factors), paged |
| Text of a filing exhibit (e.g. EX-99.1 earnings release) |
| SEC Form 4 insider transactions with transaction codes |
| XBRL fundamentals, annual or quarterly; derived values are marked |
| Margins, ROE, ROA, debt/equity, FCF margin, P/E, each with formula and source |
| End-of-day prices from the configured provider |
| Returns, max drawdown, 52-week range and volatility |
| Next earnings date per ticker (Finnhub, or an SEC-based estimate) |
| FRED series observations |
The analyze_ticker prompt
MCP clients without skill support can call the server's analyze_ticker prompt with a ticker.
It returns the same procedure as the analyze-ticker skill: a one-page brief where every number
has a source URL and date, unverifiable numbers are listed as UNVERIFIED, and there are no
recommendations.
Running tests
uv run pytest # offline, recorded fixtures; live tests are skipped by default
uv run pytest -m live # opt-in: real network and your own keys
uv run ruff check . && uv run ruff format --check .Data sources and attribution
SEC EDGAR: public-domain US government data. Follow the fair access policy: a User-Agent with your contact details and at most 10 requests/second (the server rate-limits its own requests).
FRED: This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. Use is subject to the FRED API Terms of Use. Some series are copyrighted by third parties; get the owner's permission before uses beyond personal use.
Tiingo and Finnhub: free tiers are for personal or internal use and their data may not be redistributed. Each user brings their own key; this repository's Tiingo and Finnhub test fixtures are synthetic.
yfinance (opt-in): unofficial Yahoo Finance access, personal use only.
License
MIT. Not financial, tax or legal advice.
Available Tools
11 toolsget_earnings_calendarA
Next earnings date per ticker within days_ahead days (1-180, max 20 tickers).
Source: Finnhub earnings calendar; when Finnhub has nothing (or no key / unavailable) the
date is estimated from prior SEC 8-K Item 2.02 filings and marked estimated=True.
Each row names its own method and source. No EPS or revenue forecasts are returned.
Inputs: tickers (required), days_ahead. Returns: rows, as_of, notes, stale, +5 more
get_filing_exhibitA
Plain text of one exhibit of a filing (e.g. "EX-99.1", the press release attached to
an earnings 8-K), in chunks of about 24,000 characters. Pass the returned next_cursor
to get the next chunk. Get accession numbers from list_filings. Source: SEC EDGAR.
Inputs: ticker (required), exhibit (required), accession (required), cursor. Returns: One chunk of a filing section or exhibit as plain text.
get_filing_sectionA
Plain text of one section of a 10-K or 10-Q filing, in chunks of about 24,000
characters. section: an item such as "1A", "Item 7", "7A", "1", "2", "Part II Item 1A",
or a name such as "Risk Factors" or "MD&A" (10-Q: MD&A is Part I Item 2). Pass the
returned next_cursor to get the next chunk. Get accession numbers from list_filings.
Source: SEC EDGAR.
Inputs: ticker (required), section (required), accession (required), cursor. Returns: One chunk of a filing section or exhibit as plain text.
get_fundamentalsA
Company fundamentals from SEC XBRL filings (10-K/10-Q), newest period first.
metrics: any of revenue, gross_profit, operating_income, net_income, diluted_eps,
basic_eps, operating_cash_flow, capex, total_debt, cash, shares_diluted,
shares_outstanding (default: all). periods: "annual" or "quarterly". n: number of
periods (1-40). Each value carries the XBRL tag used, the period dates, the filing's
form, accession, filed date and URL. Missing values are null with a reason.
Source: SEC EDGAR XBRL companyfacts.
Inputs: ticker (required), n, metrics, periods. Returns: cik, name, as_of, notes, +8 more
get_insider_transactionsA
Insider transactions reported on SEC Form 4, newest first: insider, role, date,
transaction code, shares, price, holdings after, derivative flag and Rule 10b5-1 flag.
Only non-derivative codes P and S count as open-market purchases/sales; derivative rows,
awards (A), tax withholding (F), option exercises (M) and other codes are labelled not
open-market. Includes Form 4/A amendments (an amendment replaces its original in the
totals). Filings where the company reports as an owner of another issuer are skipped.
since is a filing
date (YYYY-MM-DD, default 12 months ago). Source: SEC EDGAR Form 4.
Inputs: ticker (required), limit, since. Returns: cik, name, as_of, items, +12 more
get_macro_seriesA
Fetch FRED macro time series (e.g. DGS10, CPIAUCSL, UNRATE, FEDFUNDS).
Returns, per series: title, units, frequency, last_updated and observations
(date, value; missing values are null) oldest to newest, the last `limit` points
on or after `start` (YYYY-MM-DD). `as_of` is the date of the last observation.
Up to 10 series per call. Source: FRED, Federal Reserve Bank of St. Louis.
Inputs: series_ids (required), limit, start. Returns: result
get_price_historyA
Daily price bars (OHLCV plus adjusted close) for a US ticker from one price provider.
Only interval "1d" is supported. Dates are YYYY-MM-DD. Returns at most `limit` most recent
bars in the range. The response names the provider; there is no fallback to another one.
Inputs: ticker (required), end, limit, start, +1 more. Returns: bars, as_of, limit, notes, +8 more
get_price_statsB
Price statistics from one provider's adjusted closes: 1m/3m/1y/5y returns (21/63/252/1260 trading days), 5-year max drawdown with peak and trough dates, 52-week high/low and 1-year annualized volatility. Descriptive only; not a recommendation.
Inputs: ticker (required). Returns: as_of, notes, stale, source, +10 more
list_filingsA
List a company's SEC filings, newest first. Filter by form types (e.g. ["10-K",
"10-Q", "8-K"]) and filing date since (YYYY-MM-DD). Source: SEC EDGAR.
Inputs: ticker (required), forms, limit, since. Returns: cik, name, as_of, items, +8 more
pingA
Check that the market-research server is running.
Inputs: no named parameters. Returns: object
resolve_tickerA
Resolve a ticker (e.g. MSFT, BRK.B) or company name to its SEC CIK, exchange and SIC industry code. Source: SEC EDGAR.
Inputs: query (required). Returns: cik, sic, name, as_of, +8 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource: prices (history vs. stats), SEC filings (list vs. section vs. exhibit), insider transactions, fundamentals, macro series, earnings calendar. The closest pair is get_price_stats vs. get_price_history, but the stat-vs-bars distinction is clearly stated and rarely confused. The filing trio is hierarchical and the descriptions make the entry points obvious.
Uniform snake_case verb_noun convention throughout: get_*, list_*, resolve_*. Only 'ping' lacks a noun, which is conventional for a health check and does not break the pattern.
Eleven tools is squarely in the well-scoped range, and each one maps to a distinct data source or retrieval mode. No filler or redundant tools.
Strong coverage: prices, fundamentals, filings, insider activity, macro data, and earnings dates span the core research workflow. Gaps exist around earnings actuals/EPS surprises, news/sentiment, and peer comparison, but agents can work around these by combining existing tools.
Maintenance
Related MCP Connectors
Official cited financial data layer for AI agents (SEC EDGAR, FRED, ECB, Treasury, GLEIF).
SEC EDGAR financials, insider trading, and economic data for AI agents. US GAAP + IFRS.
SEC-filed company financials with filing citations, plus market data, for AI agents
Provide AI assistants with real-time access to official SEC EDGAR filings and financial data. Enab…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to access real-time stock data, financial statements, cryptocurrency information, and market data via the Financial Modeling Prep API.4MIT
- AlicenseAqualityBmaintenanceEnables Claude or any MCP host to access live market data—quotes, history, technical indicators, and NYSE status—and answer natural-language questions about stocks.4MIT
- AlicenseAqualityBmaintenanceEnables Claude to access free official financial and economic data from SEC EDGAR, U.S. Treasury, FRED, and the World Bank, including XBRL financial statements, key metrics, filings, insider trades, 13F portfolios, market prices, and macroeconomic series.20MIT
- AlicenseAqualityBmaintenanceEnables Claude to pull free, citable financial data for comps and DCF work — standardized SEC EDGAR XBRL financials, filing links, FRED Treasury yields, market prices and beta — with every value returned alongside its source concept, accession and filing URL. Provides read-only tools for company lookup, financials, filings, market data and peer comparison tables that need no API key.6MIT