cigar-butt
Provides whole-market stock bars, delisting reference data, and corporate actions via the Polygon API, used for price checks and verifying listing status, splits, and dividends.
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., "@cigar-butt screen the market for NCAV bargains and build an equal-weight allocation"
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.
cigar-butt
An MCP server that screens stocks against Benjamin Graham and Walter Schloss deep-value criteria, computing every figure from primary filings rather than from a commercial screener or from a language model's memory.
It reads SEC EDGAR XBRL to build tangible book value, NCAV, NNWC and net cash; scans the filing index for restatements, bankruptcies and delistings before doing any valuation work; and turns whatever survives into equal-weight whole-share allocations and rebalance orders.
The distinguishing claim is provenance. Every figure carries the filing it came from, the accession number and the date it was filed. A figure that could not be retrieved is reported as missing, never estimated. The failure mode this exists to prevent is the obvious one: a plausible list of tickers with plausible-looking ratios attached, assembled from training data rather than from current filings. Valuations move — a name that traded at 0.7× tangible book six months ago may trade at 2× today — and a list built from memory is confidently wrong in exactly the way that costs money.
This is not investment advice, and no advisory relationship is created by using it. The software is provided as is, without warranty, and the author accepts no liability for any loss arising from its use. Data comes from third-party sources and may be inaccurate, delayed or incomplete. Past performance does not indicate future results. You are solely responsible for your own investment decisions; consult a licensed professional. Read the full disclaimer →
Contents
Related MCP server: akyla-mcp
Why "cigar-butt"
The name is Warren Buffett's, for the style of investing he learned from Benjamin Graham. From the 1989 Berkshire Hathaway shareholder letter:
If you buy a stock at a sufficiently low price, there will usually be some hiccup in the fortunes of the business that gives you a chance to unload at a decent profit, even though the long-term performance of the business may be terrible. I call this the "cigar butt" approach to investing. A cigar butt found on the street that has only one puff left in it may not offer much of a smoke, but the "bargain purchase" will make that puff all profit.
That is the strategy this server implements: buy the discarded business nobody wants, below what its assets alone are worth, for the one puff left in it.
Buffett wrote that passage to explain why he had moved away from it. In the same letter, under the heading Mistakes of the First Twenty-Five Years, he calls the approach foolish "unless you are a liquidator", notes that "the original 'bargain' price probably will not turn out to be such a steal after all", and concludes:
Time is the friend of the wonderful business, the enemy of the mediocre.
Both halves are true and the second one is the important one here. The objections are real: at Berkshire's size the strategy stopped scaling, cheap businesses are usually cheap for a reason, and a mediocre business gets worse while you wait. Schloss ran it successfully for decades on a small book and extreme diversification — his record is commonly cited as roughly 15% a year over 45 years against about 10% for the index — which is the honest evidence for the method, and it is evidence about one manager, not a promise about yours.
A tool whose entire discipline is refusing to overstate a number should not open by overstating its strategy.
The method, honestly
The whole thesis is that the reported balance sheet is true. Everything follows from that, including the order the tools run in.
Schloss's rules, as filters:
Criterion | Filter | Note |
Below tangible book | P/TBV < 1.0 | Schloss wanted 0.6–0.8. Goodwill and intangibles are stripped out; most screeners offer plain P/B |
No real debt | Debt/Equity < 0.2 | Or long-term debt near zero |
Solvency | Current ratio > 2 | Graham's own threshold |
Diversify | 15–20 positions, equal weight | Schloss ran 60 to 100. The method distrusts per-name conviction by design |
Graham's stricter net-net variant:
NCAV = current assets − total liabilities − preferred stock. Buy below two-thirds of NCAV.
NNWC = cash + 75% of receivables + 50% of inventory − total liabilities.
Six things this does that a stock screener will not.
1. Disqualifiers run before valuation, not after. If anything undermines
the filings, the name is dead regardless of how cheap it looks, and no ratio
catches that. check_disqualifiers reads the submissions filing index in one
request and reports 8-K item 4.02 (non-reliance on previously issued
financials), 4.01 (auditor change), 1.03 (bankruptcy), 3.01 (listing
deficiency), 2.06 (material impairment), Form 25 and 25-NSE (delisting),
NT 10-K/NT 10-Q (late filing), and gaps where a periodic report should be. A
full balance sheet is twelve requests; the scan is one, so it goes first.
2. "Could not compute" is not "failed". A check reads n/a when a line
item is missing, and that is deliberately distinct from false. A filer that
never tagged Liabilities gets no NCAV — a gap in the evidence, not a failed
test. Collapsing the two is how a screen ends up confidently wrong.
3. Every line item comes from the same reporting period. Filers change which concepts they tag, so taking "the latest fact for each concept independently" can silently build NNWC from a years-old receivable. Items that do not reach the balance sheet's own period end are reported as stale and excluded from the arithmetic.
4. Enterprise value and net cash are meaningless for financials. For
SIC 6000–6799 the deposits and the securities book are not spare cash, so the
net-cash check returns n/a and says why, and debt/equity is reported without
being allowed to veto — leverage is the business model. Use bank_call_report
on those names instead: tangible common equity, noncurrent loans and the
allowance held against them are the tests that do work on a bank.
5. The debt rule and the book rule fight each other. Most persistent sub-tangible-book names are banks and insurers, whose balance sheets are debt by construction. Apply "no real debt" literally and the universe collapses to industrials, metals, shippers and foreign micro caps. Schloss owned financials anyway. The server surfaces the conflict rather than resolving it silently.
6. Net-nets are rare. A screen of the whole US market routinely returns a handful. If you want twenty strict names, the universe may not contain twenty — and loosening the filters until it does means you are no longer running this strategy. An empty US screen is a real finding; say so, or look at Japan, where they have been considerably less scarce.
Getting started
Requires Node 24.21.0 or later (see .nvmrc). The cache uses node:sqlite,
which needs no flag on Node 24.
Claude Code
claude mcp add cigar-butt -- npx -y cigar-buttClaude Desktop, Cursor and other MCP clients
{
"mcpServers": {
"cigar-butt": {
"command": "npx",
"args": ["-y", "cigar-butt"],
"env": {
"SEC_USER_AGENT": "Your Name your-email@example.com"
}
}
}
}The env block is optional. With no credentials at all, a large part of the
server still works, and the tools that need one say exactly which one and how
to get it.
Once connected, ask the model to run setup_status, or open the
Set up cigar-butt prompt the server registers, which lists every credential
and how to obtain it.
From source
git clone https://github.com/mainfraame/cigar-butt.git
cd cigar-butt
pnpm install
pnpm build
node dist/index.jsCredentials
Credentials are optional and checked per tool. Nothing is globally blocked: a tool asks only for what it actually uses, so the rest of the server keeps working while you fill things in.
Tier | What you get |
No credential at all | Congressional disclosures, FINRA short interest, FDIC call reports, UK Companies House status, ECB exchange rates, and all the allocation and rebalance arithmetic |
|
|
Any one price provider |
|
Optional extras | FRED for the macro context, E*TRADE for reading your real book, Companies House and EDINET for the UK and Japan |
Every tier listed is free.
To set them up, call setup_credentials. On a client that supports
elicitation the server prompts for each value directly; otherwise it returns
the registration links for the model to relay, and you pass the values back.
They are written to a 0600 JSON file under your config directory, never into
a project. Environment variables win over the stored file, so you can override
one value for a single run.
Full credentials reference → — every integration, sign-up links, step-by-step instructions (including how to obtain E*TRADE sandbox and production keys), the
credentials.jsonshape and every environment variable. Generated from the provider registry, so it cannot drift from what the server actually reads.
Two things worth knowing before you get there:
SEC EDGAR has no API key. A fake User-Agent is worse than none: EDGAR may block your IP.
E*TRADE issues two independent key pairs, sandbox and production, and they are not interchangeable. Both pairs and both access tokens are stored separately, so switching with
broker_environmentcan never sign a production request with sandbox material. Sandbox returns canned data that does not match what you asked for — request GOOG, get AAPL — so use it to prove the connection works, never to read real numbers.
What you can do with it
Thirty-eight tools, grouped by what you are trying to do. The order below is roughly the order they are meant to run in; the server ships the same order of operations to the model as its instructions.
Set the server up
Tool | What it does |
| Which credentials are configured, where each value came from, sign-up URLs for what is not |
| Prompt for and store credentials in the |
| Every price provider: key, rate, budget consumed, and whether it is sitting out a cap |
| What the local response cache holds, by source, and where the database lives |
| Drop cached responses so the next call refetches. |
Screen the market
Tool | What it does |
| Every SEC filer that reported in a quarter, via the XBRL |
screen_market attaches no prices, on purpose: pairing a stale quote with
a filing figure is the mistake this server exists to prevent. Its output is a
candidate list for analyze_ticker, not a verdict.
Check the name is not already dead
Tool | What it does |
| One request against the SEC filing index: restatements, auditor changes, bankruptcy, delisting, late filings |
| The text of a filing, optionally scoped to one 8-K item. Item 3.01 covers both losing listing compliance and regaining it — only the words tell you which |
| The UK analogue, from the Companies House register: liquidation, administration, strike-off, overdue accounts, insolvency history, charges over assets |
Run these before any valuation work.
Verify one name
Tool | What it does |
| The full workup: disqualifier scan, then tangible book, NCAV, NNWC and net cash from XBRL line items, then a dated price, then the Schloss and Graham verdicts. Stops before valuation if the name is disqualified |
| Current prices for a list of tickers, each with its as-of date and the provider it came from |
| Listing status, splits and dividends. A split between the balance-sheet date and today makes every per-share figure wrong by the split factor |
| FINRA consolidated short interest — the market's own answer to "why is this cheap?". Context, not a veto |
| FDIC call reports: tangible common equity, noncurrent loans, allowance coverage. The asset tests that work on a financial |
Look outside the US
Tool | What it does |
| Japanese filings by company name, TSE ticker or EDINET code, from the FSA's EDINET. Indexed by date, not by company, so it walks back a day per request — annual reports cluster in late June |
| Balance-sheet line items and the Graham tests for a Japanese filer, from its EDINET XBRL, converted at a dated ECB rate |
| Find a UK company on the Companies House register and get its company number |
| Exchange rates from the ECB, current or historical. A balance sheet in yen cannot be compared against a dollar cash balance without one |
uk_company_status returns no financials: UK accounts are filed as iXBRL or
PDF documents rather than structured data, so the UK path is a disqualifier
check, not a valuation.
Size a book and rebalance it
Tool | What it does |
| Verified candidates plus a cash balance into whole-share targets. Equal weight, per-name cap, always rounds down so the plan cannot exceed the balance |
| Current holdings against target weights into buys, sells and full exits. Compares market value rather than share count, reports sells before the buys they fund, and says when the buys are not fundable |
Only pass names you have actually verified. A weighting implies a level of diligence a screen does not provide.
Read your actual portfolio
Read-only. This server never places, modifies or cancels an order.
Every tool here reads all connected brokerages as one book. Two hundred shares at one broker and a hundred at another is a three-hundred-share position, and weighting it per broker would be wrong at the only level that matters. What the combined view never loses is where the shares actually sit: a sale happens at a broker, and which one decides its tax consequence.
Tool | What it does |
| Authorize a broker that needs it. E*TRADE returns a URL and shows a short code out of band, which you pass back as |
| Every account at every connected broker, with the |
| The whole book, combined per ticker and marked at each broker's last trade with that trade's date, emitted in exactly the shape |
| Cash available to invest, settled versus unsettled, total value and open margin calls, per account and summed |
| Trades, dividends, transfers and fees for one account — history is where basis is reconstructed, and interleaving two ledgers would obscure it |
| Show or switch which book each broker is pointed at, without mixing credentials |
| Revoke and delete a stored session token, leaving the API keys in place |
Supported today: E*TRADE and Alpaca, plus Fidelity read-only.
Fidelity has no public retail API, so its adapter uses the services its own
website calls, authenticated by a browser session cookie you copy into
FIDELITY_COOKIE — it expires with the session and can break when Fidelity
changes its site. It reads Brokerage-account positions and balances only: no
orders, no transaction history, no 401(k) plans. Adding a third is an adapter
against BrokerAdapter plus one line in the registry — no tool changes.
Four things the combined view does that a per-broker one cannot.
It never sums a simulated book into a real one. If one broker is live and
another is in its paper or sandbox book, the live side is used and the other is
excluded by name. Synthetic cash folded into a real balance is a figure someone
could size an allocation against, and E*TRADE's sandbox in particular answers a
request for GOOG with AAPL. Pass broker to read a simulated book on its own.
A broker that is down does not hide the rest. Its accounts are reported as missing and every affected total says it is short — a plan built from a book that quietly lost a broker is worse than one that admits a gap.
Tax treatment does not combine. The same ticker in a Roth and a taxable
account has no single answer to "does selling realise a gain?". That reads
mixed, the handoff to plan_rebalance says unknown, and no gain figure is
offered for those names. Which account a sale comes out of is your decision.
Disagreeing marks are reported, not averaged. Two brokers can quote the same security differently, usually because one is showing a last trade from an earlier session. The newest mark is used and the gap is named.
E*TRADE tokens die at midnight US Eastern. They also go idle after two hours, which the server renews automatically; midnight it cannot. There is no refresh token, so re-authorising needs a human to read a verifier code back. Alpaca uses static API keys and has no such expiry, which makes it the better choice for anything scheduled.
Monitor positions between sessions
Tool | What it does |
| Recent runs, snapshot age, rules armed, file locations. Check this before trusting that anything is being watched |
| Alerts fired, each with the reference price and its date, the observed price and its date, and the rule that tripped |
| The armed rules and their thresholds |
| Create or update a price-move alarm. Local state only; never touches the broker |
| Delete a rule and its recorded reference prices |
| Record the holdings to monitor, in the shape |
| Forget the recorded holdings, when the snapshot no longer describes the book |
See Scheduled monitoring for how this runs when no session is open, and what it genuinely cannot do.
Understand the context
Tool | What it does |
| Moody's Aaa yield, the 10-year, CPI, and the P/E ceiling they imply. Graham wanted an earnings yield of at least twice the Aaa yield, so the hurdle moves with the bond market. Needs a FRED key |
| Liquidity, days to sell a position of a given size, distance below the 52-week high, normal daily move |
| Disclosed Senate transactions searchable by ticker or member, with each member's committee seats |
| How much Senate disclosure history is indexed locally, and backfill further |
| A senator's committees, board seats and outside positions, plus every employer paying the household |
| House transaction-report filings with PDF links — the filing record, not the transactions inside it |
Two warnings the tools repeat in their own output.
price_history_stats is not part of the screen. This is an asset test; no
statistic in that tool bears on whether a balance sheet is cheap, and none of
it may be used to time a purchase. Its one legitimate veto is liquidity — deep
value lives in micro caps where the discount is often just the illiquidity, and
a name you cannot exit is a name you cannot own. RSI, MACD and every other
timing construct are deliberately absent.
Congressional disclosures sit outside the method. Amounts are bands
reported weeks late, so nothing there can be a figure the screen acts on. The
committee cross-reference is the part carrying real information. eFD cannot be
searched by ticker — its form takes a filer name, a state and a filing-date
window and nothing else — so transactions are parsed into a local SQLite index
and queried there; congress_index reports how deep that index reaches, and a
search finds only what has been indexed.
How it gets its data
SEC EDGAR is authoritative and everything else is a cross-check. EDGAR is the filing itself: exact line items, each carrying its accession number, form type, period end and filing date. A vendor's normalisation of a filing loses to the filing, and derived "net cash" figures from screeners have been wrong in testing.
Endpoint | Used for |
| One concept, full history, small payload. The workhorse for balance-sheet work |
| One concept across every filer in a period. This is the market-wide screen |
| The filing index, including the 8-K |
Every price carries its date. In testing, two fetches of one ticker minutes
apart returned $18.42 dated Sep 4 and $15.50 dated Jul 10 — a 19% spread on the
same security, hours apart, both presented as "the price". A number without its
date is arbitrary, which is why Quote.asOf is not optional, why a computed
metric reports the date of its oldest input rather than its newest, and why a
rebalance plan flags any order whose price is undated.
Sources that need no credential at all: SEC EDGAR (a contact string, not a
key), FINRA, FDIC BankFind, Senate eFD, the House Clerk's index, the
unitedstates/congress-legislators rosters, and Frankfurter for ECB reference
rates.
Price providers and free-tier caps
Quote providers are a failover pool, not a fixed chain. A request tries them in order and skips any that has no key, is cooling down, or has spent its budget. Any one of them is enough; more simply buys headroom.
Provider | Free tier | Notes |
Tiingo | ~50 unique tickers/hour, 500 requests/day | Split- and dividend-adjusted. The preferred source |
Polygon.io | 5/minute, end-of-day, ~2 years of history | Also the reference data behind |
Finnhub | 60/minute, no daily cap | The most generous free quote tier here |
Twelve Data | 8/minute, 800/day | Carries an explicit trade date |
Alpaca | 200/minute on the free plan | Most headroom of any tier here. IEX feed, so a thin micro cap may not have printed at all |
Financial Modeling Prep | 250/day | Free tier restricted to large caps |
Alpha Vantage | 5/minute, 25/day | Effectively a spot-check |
EOD Historical Data | 20/day | The only non-US coverage. Pass |
Usage is counted locally and checked before a request goes out, against each service's documented limits, rather than inferred from a 429 afterwards. On a daily cap that distinction matters: a rejected call still counts against you, so learning reactively spends a request that was never going to work. A 429 is still honoured as a backstop, since the same key may be in use elsewhere. Counters live in SQLite and survive a restart, because a daily quota does not reset just because the process did.
Tiingo meters unique symbols per month, not only requests, so a single large screen can spend a substantial share of the month while the request counters still look healthy. Distinct symbols are tracked separately; re-reading one already counted this month is free.
If you pay for a plan
The defaults above are free-tier limits, so without overriding them a paid plan runs at free speed.
Variable | Effect |
| Call budget, e.g. |
| Requests per second, e.g. |
| Preference order, e.g. |
Caching
Responses are cached in SQLite (node:sqlite, built into Node 24, so it costs
no dependency). The free tiers are the binding constraint: a full per-name
balance sheet is twelve companyconcept calls plus a submissions fetch. MCP
servers also restart whenever a client reconnects, so an in-memory cache would
throw the expensive work away at every session boundary.
TTLs are set by how fast the underlying fact can actually change.
Source | TTL | Why |
Quotes | 1 hour | Short on purpose. A stale price is the single largest source of wrong answers here |
SEC balance-sheet concepts | 24 hours | These change only when a filing lands |
SEC filing index | 6 hours | Gains rows continuously; a new 8-K must not be missed |
SEC frames | 7 days | A quarter's data is fixed once filed |
Ticker index | 7 days | A ~1MB payload that changes at the margins |
Quotes are cached per provider, because two providers can legitimately disagree
and blending them under one key would hide it. cache_status shows what is
held, cache_clear drops it, and CIGAR_BUTT_NO_CACHE=1 bypasses it entirely.
Scheduled monitoring
cigar-butt watch polls your holdings on a timer and alerts on moves beyond a
threshold you set. Bare cigar-butt is still the MCP server; only the explicit
watch subcommand branches away.
cigar-butt watch rule add drawdown '*' 10 # alert on any held name moving 10%
cigar-butt watch install # write a launchd agent (macOS)
launchctl load -w ~/Library/LaunchAgents/dev.cigar-butt.watch.plist
cigar-butt watch statuscigar-butt watch with no arguments prints the full subcommand list. The
watch_* tools do the same work over the same database from inside a session.
Nothing here places, modifies or cancels an order.
The MCP server cannot schedule anything. A stdio server is a subprocess and
dies with its client, and the protocol gives a server no way to reach an absent
user, on any transport. So the OS scheduler runs a short-lived watch run, and
the server reads what it recorded. See
docs/scheduling-research.md for why this shape
and not a daemon, and what is genuinely impossible.
Three limits worth knowing before relying on it:
Alarm latency is the poll interval. That is what free price tiers buy: Alpha Vantage allows 25 requests a day, Tiingo about 50 an hour, and a 20-name book polled every 15 minutes would exhaust them by lunchtime. This is a check, not a tripwire.
Price alarms need no broker. They run against a stored holdings snapshot using only a price key, so they work overnight, at weekends, and indefinitely.
Broker refresh does not survive midnight. E*TRADE tokens expire at midnight US Eastern with no refresh token. Refresh the snapshot while you are authorised; every alert states the snapshot's age rather than pretending it is current.
Alerts go to stderr, a log file, a macOS notification, or a Slack/Discord
webhook (CIGAR_BUTT_WATCH_WEBHOOK). Test one before you need it:
cigar-butt watch test macos. A cooldown, a hysteresis latch, optional
re-baselining and one notification per cycle keep alerts from storming.
What it will not do
It will not place a trade unless you switch that on, twice. Every
brokerage tool was read-only until order placement was added behind two
independent switches: CIGAR_BUTT_ENABLE_ORDERS=1 enables paper and sandbox
books, and real money additionally needs CIGAR_BUTT_ENABLE_LIVE_ORDERS=1. A
fresh install cannot trade whatever anything asks of it.
Where it is enabled, no single call both decides and executes: order_preview
prices an order and returns a ref, and order_place takes only a ref. Orders
are limit-only, day-only, whole-share, and capped per order
(CIGAR_BUTT_MAX_ORDER_VALUE, default $2,500). The risk being guarded against
is not you mistyping a ticket — it is an assistant sending an order you never
saw.
It will not backtest. A backtest assembled from a list picked with present-day knowledge is survivorship-biased by construction: you chose those names partly because they still exist, so any return figure flatters the strategy. Free price sources are neither survivorship-bias-free nor point-in-time correct, which is exactly what a research database like CRSP buys you. For a real backtest, use point-in-time data with delistings included.
It will not estimate what a trade costs. For a micro-cap book the published
fee is a rounding error and the bid-ask spread is the trade cost, and the ratio
between them is roughly two orders of magnitude: about $0.41 of statutory
charges on a $10,000 sale, against a plausible several hundred dollars of
round-trip spread. Spread and market impact are not observable from anything
here, so they are not estimated — printing a precise figure for the $0.41 while
saying nothing about the rest would be read as the cost. Fee figures in the
output are statutory charges only. See
docs/trading-costs-research.md.
It will not compute a tax liability. It reports the account classification
and cost basis a broker records, and will do arithmetic on two figures it was
given, but holding period, wash sales and basis adjustments are not modelled,
and a number that looked like a tax bill would be believed as one. An account
whose tax treatment reads unknown is undetermined and is never assumed
taxable. See
docs/tax-treatment-research.md.
It will not name a stock it has not fetched this session. A name reaches the output only with a dated figure behind it.
Configuration reference
Variable | Default | Purpose |
| unset | Load credentials from this dotenv file |
|
| Where credentials are stored |
|
| Cache database location |
| unset | Set to |
| under the cache directory | Senate disclosure index location |
| under the cache directory | Watch state: snapshot, rules, alerts |
| unset | Write watch alerts to this file |
| unset | Slack or Discord webhook for alerts |
| under the cache directory | Remembered tool preferences |
Provider budgets and rates are in
Price providers; every credential
variable is in docs/credentials.md, and
.env.template is a complete annotated file.
Development
pnpm install
pnpm check # lint, format:check, typecheck, knip, test
pnpm test # vitest
pnpm build # tsdown → dist/index.js
pnpm dev # tsx watchConcern | Tool |
Package manager | pnpm |
Bundler | tsdown (rolldown) |
Lint | oxlint, with |
Format | oxfmt, including its built-in import sorting |
Dead code and deps | |
Tests |
Two rules that are not obvious from the code:
All arithmetic goes through decimal.js. number appears at the I/O
boundary — JSON in from an API, JSON out to the MCP client — and nowhere in
between. Partly for pennies, mostly because these figures are compared against
hard thresholds: binary floating point puts a name on the wrong side of "P/TBV
below 1.0" often enough to matter when the whole method is buy below the
line.
Nothing may write to stdout. That stream is the MCP protocol. A stray
console.log corrupts it and the client drops the connection, which is why
no-console is an error across src/ and why the watch CLI prints to stderr.
CLAUDE.md has the full architecture and the hard rules;
STYLEGUIDE.md has the TypeScript conventions.
docs/credentials.md is generated from src/config/providers.ts by
pnpm docs:credentials — do not edit it by hand.
Disclaimer and licence
This software is not investment, financial, tax or legal advice, creates no advisory or fiduciary relationship, comes with no warranty of any kind, and its author accepts no liability for any loss arising from its use. Read DISCLAIMER.md in full before using it for anything involving real money.
Licensed under Apache-2.0. See LICENSE, whose sections 7 and 8 carry the warranty disclaimer and limitation of liability that govern.
Available Tools
29 toolsanalyze_tickerAnalyze one tickerARead-only
Full deep-value workup for one name: the disqualifier scan first, then tangible book, NCAV, NNWC and net cash computed from SEC XBRL line items, then a current price, then the Schloss and Graham verdicts. Every figure carries the filing it came from and the date it was filed. Returns the disqualifier findings and stops before valuation if the name is disqualified.
Inputs: ticker (required), skipDisqualifiers.
bank_call_reportFDIC call report for a bankARead-only
Pull the latest FDIC call report for a bank, by name or FDIC certificate number. This is the asset test that works on a financial: enterprise value and net cash are meaningless for SIC 6000-6799, but tangible common equity over tangible assets, noncurrent loans over net loans, and the allowance held against those loans are exactly the figures a Schloss screen on a bank turns on. Straight from the quarterly call report, dated by report date. No credential required. Search by the holding company name — the SEC filer — and it will also match the insured bank underneath it.
Inputs: cert, name, limit.
build_allocationBuild an allocationARead-only
Turn a verified candidate list and a cash balance into whole-share position targets. Equal weight by default, with a per-name cap and whole-share rounding that always rounds down, so the plan can never exceed the balance. Only pass names you have actually verified with analyze_ticker: a weighting implies a level of diligence a screen does not provide.
Inputs: candidates (required), availableCash (required), perTradeCost, maxPositionFraction, +1 more.
cache_clearClear the cacheADestructiveIdempotent
Drop cached responses so the next call refetches. Pass a source to clear just that one, or omit to clear everything. Use expiredOnly for routine housekeeping, which never discards a live entry.
Inputs: source, expiredOnly.
cache_statusInspect the cacheARead-only
Report what the local response cache holds, by source, and where the database file lives. Useful when a figure looks stale or when you want to know whether the next screen will hit the network.
Inputs: no named parameters.
check_corporate_actionsCheck listing status and corporate actionsARead-only
Check listing status and corporate actions for a ticker against Polygon reference data. Two things this catches that a ratio cannot. A split between the balance-sheet date and today makes every per-share figure derived from the filing wrong — the share count is pre-split and the price is post-split — and a reverse split makes a name look cheap by exactly the split factor. And a delisted ticker still resolves in the EDGAR index long after it stopped trading. Pass the balance-sheet period end as since.
Inputs: ticker (required), since, includeDividends.
check_disqualifiersScan filing index for disqualifiersARead-only
Scan a company's SEC filing index for the events that void a deep-value thesis: 8-K item 4.02 (non-reliance on prior financials), 4.01 (auditor change), 1.03 (bankruptcy), 3.01 (listing deficiency), 2.06 (impairment), Form 25/25-NSE (delisting), NT 10-Q/NT 10-K (late filing), and filing gaps. Costs one request. Run this BEFORE any valuation work — a name that fails here is dead regardless of how cheap it looks, and no ratio would catch it.
Inputs: ticker (required), lookbackDays.
congress_house_filingsHouse transaction-report filingsARead-only
Periodic transaction reports filed by House members, from the Clerk's official yearly index. No credential needed. This returns the filing record and a link to the PDF, NOT the transactions inside it — House disclosures are PDFs and many are scanned images, so the tickers and amounts are only readable by opening the document. For actual transaction detail use congress_trades, which covers the Senate.
Inputs: year, member, sinceDays.
congress_indexInspect or extend the disclosure indexA
Show how much Senate disclosure history is indexed locally, and extend it. Call with no arguments to report coverage; pass sinceDays to backfill. Each report is a separate request against a rate-limited government site, so work is capped per call and resumes where it left off — reports already indexed are never refetched, because a filed report never changes. Rough sizes: 12 months is ~180 reports, five years ~690, and the whole archive back to 2012 is ~2,400. Expect to call this several times to build deep history; each call reports how many reports remain.
Inputs: sinceDays, maxReports.
congress_member_profileCommittee seats and outside interestsARead-only
A senator's committee assignments, outside positions and board seats, and every employer paying the household — self, spouse or child — read from their most recent annual financial disclosure. This is the conflict-of-interest picture behind a trade: which industries they have authority over, which boards they sit on, and who else pays the family. Senate only; House annual disclosures are scanned PDFs.
Inputs: member (required).
congress_tradesSearch congressional trades by tickerARead-only
Search disclosed Senate stock transactions by ticker, by member, or both. No credential needed. This is the natural entry point: ask "who in the Senate traded ASTE?" and get every disclosed transaction in the index, with the committees each member sits on.
eFD itself cannot be searched by ticker — its form takes a filer name, a state and a filing-date window and nothing else — so transactions are held in a local index. It refreshes itself when stale, and reports are immutable once filed, so keeping current costs only the new filings. Use congress_index to see how deep the index reaches and to backfill further; a search can only find what has been indexed.
Inputs: limit, member, ticker, sinceDays.
edinet_financialsJapanese balance sheet (EDINET)ARead-only
Balance-sheet line items and the Graham asset tests for a Japanese filer, read from its EDINET XBRL filing. Figures are in yen and converted to a currency of your choice at a dated ECB reference rate.
This is the point of the Japanese path: net-nets have been far scarcer in the US than in Japan for a decade, and a Graham screen that cannot read these filings is looking in the wrong market. Get a document ID from edinet_search first.
Inputs: docId (required), convertTo.
edinet_searchSearch Japanese filings (EDINET)ARead-only
Find recent Japanese regulatory filings by company name, TSE ticker or EDINET code, from the FSA’s EDINET system — Japan’s equivalent of SEC EDGAR. Returns document ids to pass to edinet_financials.
EDINET has no search-by-company endpoint; it is indexed by date, so this walks back one day at a time and each day is a request. Annual reports cluster in late June, because most Japanese companies close their books on 31 March and file within three months — so searching ten days in November will usually find nothing even for a company that files reliably. Set startDate to late June to look for an annual report.
Inputs: query (required), maxDays, startDate, annualOnly.
etrade_accountsList E*TRADE accountsARead-only
List the ETRADE accounts this connection can read, with the accountIdKey every other ETRADE tool needs. Call this before etrade_positions — the account number a user quotes is not the key the API accepts.
Inputs: no named parameters.
etrade_balancesRead E*TRADE balancesARead-only
Full balance detail for one E*TRADE account: cash available to invest, settled versus unsettled, buying power, margin balance, market value, and any open margin calls. Use this when the question is "what do I have to deploy?" — etrade_positions answers "what do I hold?".
Inputs: accountIdKey (required).
etrade_connectConnect an E*TRADE accountA
Connect this server to an ETRADE brokerage account over OAuth 1.0a. Call with no arguments to get an authorization URL for the user to open; ETRADE shows them a short verification code, which you pass back as verifier on a second call. There is no browser redirect — ETRADE issues the code out-of-band, which is why the user has to read it back to you. ETRADE access tokens go idle after two hours without a request and expire outright at midnight US Eastern, no matter how recently they were used. After midnight the user must authorize again; there is no refresh token. Call this tool again whenever another E*TRADE tool reports an expired token. While a connection is live the server renews it in the background every ninety minutes, so the idle timeout should never be what ends a session — only midnight does.
Inputs: verifier.
etrade_disconnectDisconnect E*TRADEADestructiveIdempotent
Revoke the stored E*TRADE access token and delete it, ending the session. The consumer key and secret are left in place, so etrade_connect can reconnect without re-entering them. Use this when handing the machine over, switching between the sandbox and production key pairs, or when a token is behaving oddly.
Inputs: no named parameters.
etrade_environmentShow or switch E*TRADE environmentAIdempotent
Show or switch which E*TRADE environment is active. Call with no argument to see which key pairs are configured and which is in use; pass environment to switch. Sandbox and production hold entirely separate keys AND separate access tokens, so switching never mixes credentials and never invalidates the other side — you can keep both connected and flip between them. Sandbox returns canned data that does not match what you ask for, so use production for any real figure.
Inputs: environment.
etrade_positionsRead E*TRADE positions and cashARead-only
Current holdings and investable cash for one E*TRADE account, each position marked at its last trade with the date that trade happened. The response ends with a JSON block in exactly the shape plan_rebalance takes for its holdings argument, plus the cash figure for availableCash, so a rebalance can be planned against the real book without the user retyping it. Positions that came back without a symbol or a usable mark are omitted: an undated or unpriced position cannot be sized against.
Inputs: accountIdKey (required).
etrade_transactionsRead E*TRADE transactionsARead-only
Transaction history for one ETRADE account as a table: trades, dividends, transfers and fees, each with its date, symbol, quantity, price and amount. ETRADE keeps two years and pages at 50 rows. Useful for reconstructing cost basis, checking what a rebalance actually executed at, and separating dividend income from realised gains.
Inputs: accountIdKey (required), count, symbol, endDate, +1 more.
fx_rateExchange rateARead-only
Exchange rate between two currencies, from the European Central Bank's daily reference rates via Frankfurter. No credential, no cap. Needed whenever a screen leaves the US — a balance sheet in yen cannot be compared against a dollar cash balance without one. Pass a date to get a historical rate, which is what a return calculation across currencies requires.
Inputs: base (required), quote (required), on.
get_quotesGet current pricesARead-only
Current prices for a list of tickers, each with the date it is as of and the provider it came from. Providers are tried in order (Tiingo, Polygon, Alpha Vantage) and every failure is reported, so "no key", "bad ticker" and "rate limited" stay distinguishable.
Inputs: tickers (required).
macro_contextMacro context for the Graham testsARead-only
Fetch the macro figures Graham's tests are stated against: the Moody's Aaa corporate bond yield, the 10-year Treasury, and CPI with its trailing twelve-month change. Graham required an earnings yield of at least twice the Aaa yield, so the P/E a name must beat moves with the bond market — a fixed ceiling quoted from the book applies a 1973 bond yield to a current balance sheet. Every figure carries the date it is for. Needs a FRED key.
Inputs: priceEarnings.
plan_rebalancePlan a rebalanceARead-only
Compare current holdings against a target allocation and produce the buys, sells and full exits that close the gap. Compares market value, not share count, so a name that has re-rated shows as overweight. Sells are reported before buys because the proceeds fund them, and the plan says explicitly when the buys are not fundable from cash plus proceeds.
Inputs: targets (required), holdings (required), availableCash, minTradeValue, +2 more.
provider_statusPrice provider statusAIdempotent
Show every price provider: whether it has a key, the rate it is being called at, and whether it is currently sitting out a free-tier cap. Providers are a failover pool — a request tries them in order and skips any that is unconfigured or cooling down — so this answers "why did that quote come from there?" and "why is this slow?". Pass clearCooldowns to forget recorded caps, which is worth doing when you know a daily quota has reset or you have just upgraded a plan.
Inputs: clearCooldowns.
screen_marketScreen the whole marketARead-only
Screen every SEC filer that reported in a quarter, using the XBRL frames endpoint. Five requests total regardless of universe size. Computes tangible book and NCAV for the whole market from primary filing data — no commercial screener. Returns candidates ranked by NCAV as a share of tangible book. It attaches NO prices: pairing a stale quote with a filing figure is the mistake this server exists to prevent, so run analyze_ticker on the survivors to get a dated price and a verdict.
Inputs: period (required), limit, minNcavRatio, minTangibleBook.
setup_credentialsConfigure API credentialsAIdempotent
Store API credentials for this server. Call with no arguments to prompt the user for them. Call with arguments to save values the user has already given you. Values are written to a 0600 file in the user config directory, never into a project. Pass an empty string to remove a credential.
Inputs: FMP_API_KEY, FRED_API_KEY, EODHD_API_KEY, EDINET_API_KEY, +12 more.
setup_statusCheck credential setupARead-only
Report which API credentials are configured, where each value came from, and the sign-up URL for anything missing. Call this first in a new session, and whenever another tool reports that the server is not configured.
Inputs: no named parameters.
short_interestShort interestARead-only
FINRA consolidated short interest for one ticker — the market's own answer to "why is this cheap?". Free, no credential. Reports shares short, days to cover, and the trend across the reporting window. Heavy short interest on a sub-tangible-book name belongs in the reason the name is cheap; it is not an automatic veto, and Schloss owned plenty of names the market disliked.
Inputs: ticker (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Tools target well-separated purposes across distinct domains (SEC valuation, E*TRADE brokerage, Congress disclosures, Japanese EDINET, cache/provider infra). There is minor friction where check_disqualifiers overlaps with analyze_ticker (which also runs a disqualifier scan) and etrade_balances vs etrade_positions are close, but the descriptions explicitly draw those lines ("what do I have to deploy?" vs "what do I hold?"). An agent can reliably pick the right tool.
Everything is uniformly snake_case with consistent family prefixes (etrade_*, congress_*, edinet_*, cache_*, setup_*), which makes grouping obvious. The verb style is not uniform—some are verb_noun (get_quotes, analyze_ticker, plan_rebalance) while others are noun_noun (short_interest, fx_rate, bank_call_report)—so it falls short of a single predictable pattern.
29 tools is on the heavy side and sits at the boundary of the 'too many' band, though the breadth of scope (brokerage, SEC analysis, Congress, Japan, caching) justifies most of them. A few could be consolidated (cache_status/cache_clear, the E*TRADE credential tools), but each domain genuinely needs its surface.
Coverage of the deep-value workflow is strong end-to-end: screen_market → check_disqualifiers → analyze_ticker → quotes/macro/fx/corporate-actions → build_allocation → plan_rebalance, plus brokerage read and disclosure data. The main gap is that the E*TRADE integration is read-only—there is no order-placement tool, so a rebalance plan can be produced but not executed through the server.
Related MCP Connectors
Intrinsic stock value from SEC filings: DCF, EPV, Graham, moat signals. Deterministic, not guessed.
Stock valuations, fundamentals, bounded screens, and OAuth-enabled portfolio research.
SEC EDGAR financials, benchmarks, screening & Buffett value scans for agents. Pay x402 or API key.
Quantitative and qualitative SEC stock and options screener across 7,100+ public filers.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables aggregated investment research by combining data from Yahoo/SEC EDGAR, Finnhub, and GDELT with analysis modules for price momentum, news signals, and estimate revisions.MIT

akyla-mcpofficial
AlicenseAqualityDmaintenanceProvides as-reported US equity fundamentals, live quotes, financial statements, valuation comps, and a screener from SEC filings, with per-cell filing provenance for citations.7MIT- FlicenseNot gradedqualityDmaintenanceProvides financial stock analysis for U.S. public companies via SEC EDGAR APIs, offering tools to resolve companies, retrieve filings, calculate profitability metrics, compare periods, detect red flags, and get audit evidence, all without API keys.-
- AlicenseNot gradedqualityBmaintenanceEnables free financial data analysis from SEC EDGAR filings, including company fundamentals, DCF valuation, comparable companies, industry benchmarks, and stock screening, with no API key required.81 npm1Apache 2.0