Skip to main content
Glama
market-research-mcp

market-research-mcp

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 .env file.

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

SEC_USER_AGENT

Yes, for all SEC tools

No signup. Your name and email, e.g. Jane Doe jane@example.com (SEC policy)

Free. Max 10 requests/second

FRED_API_KEY

For get_macro_series

fredaccount.stlouisfed.org/apikeys

Free. The terms publish no numeric limit; 120 requests/minute is commonly cited (UNVERIFIED)

TIINGO_API_KEY

For price tools (default provider)

tiingo.com/account/api/token

Starter: 50 requests/hour, 1,000/day, 500 unique symbols/month, internal (personal) use only (pricing)

FINNHUB_API_KEY

Optional, for announced earnings dates

finnhub.io/register

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

PRICE_PROVIDER

Optional

tiingo (default) or yfinance (unofficial; uv sync --extra yfinance)

n/a

CACHE_PATH

Optional

SQLite cache, default ~/.market-research/cache.db

n/a

LOG_LEVEL

Optional

Default INFO; logs go to stderr

n/a

JOURNAL_DIR

Optional

Briefs go to <JOURNAL_DIR>/analyses/, otherwise ./analyses/

n/a

MRM_ENV_FILE

Optional

Path of a .env file to use instead of the per-user one

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:

  1. Real environment variables.

  2. The file named by MRM_ENV_FILE, if set. Otherwise the per-user file: %APPDATA%\market-research-mcp\.env on Windows, ~/.config/market-research-mcp/.env elsewhere ($XDG_CONFIG_HOME is honoured).

  3. .env in 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

  1. Install uv and create the per-user .env above with at least SEC_USER_AGENT.

  2. In Claude Code: /plugin marketplace add romanmoravskyi/market-research-mcp

  3. /plugin install market-research@market-research-mcp, then restart Claude Code or run /reload-plugins.

  4. 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 sync

Claude 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-mcp

Tools

Tool

What it returns

ping

Server status and version

resolve_ticker

Company name, CIK, exchange and SIC code from SEC

list_filings

SEC filings for a ticker, filtered by form and date

get_filing_section

Text of one 10-K/10-Q item (e.g. 1A risk factors), paged

get_filing_exhibit

Text of a filing exhibit (e.g. EX-99.1 earnings release)

get_insider_transactions

SEC Form 4 insider transactions with transaction codes

get_fundamentals

XBRL fundamentals, annual or quarterly; derived values are marked

get_key_ratios

Margins, ROE, ROA, debt/equity, FCF margin, P/E, each with formula and source

get_price_history

End-of-day prices from the configured provider

get_price_stats

Returns, max drawdown, 52-week range and volatility

get_earnings_calendar

Next earnings date per ticker (Finnhub, or an SEC-based estimate)

get_macro_series

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 tools
get_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

    A3.9/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to access real-time stock data, financial statements, cryptocurrency information, and market data via the Financial Modeling Prep API.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude or any MCP host to access live market data—quotes, history, technical indicators, and NYSE status—and answer natural-language questions about stocks.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      20
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      6
      MIT