io.github.alphasmo/alphasmo-tools
CLI + MCP server for SEC 13F institutional holdings, insider trading, and smart money convergence.
Open source Open in the app JSON README (API)
About
CLI + MCP server for SEC 13F institutional holdings, insider trading, and smart money convergence.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- alphasmo
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.1
- Stars
- 2
- Last push
- 2026-08-12T15:09:50Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.alphasmo/alphasmo-tools
README
# AlphaSMO — The Ultimate Smart Money API for AI
[](https://www.npmjs.com/package/alphasmo)
[](LICENSE)
**CLI + [MCP server](https://modelcontextprotocol.io) for [AlphaSMO](https://alphasmo.com)** — SEC EDGAR 13F institutional holdings, Form 4 insider trading, and "smart money convergence" signals (tickers where hedge funds *and* company insiders are buying at the same time), queryable from your terminal, your scripts, or any MCP-compatible AI agent (Claude, ChatGPT, Cursor, etc.).
No signup, no API key, no setup — try it right now:
```bash
npx alphasmo stocks flows --limit 10
```
**Example output:**
```text
┌────────┬──────────────────────────────┬────────────────────┬──────────────┬──────────────┐
│ ticker │ issuer │ net flow (USD) │ avg weight % │ institutions │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ BRK-A │ BERKSHIRE HATHAWAY INC-CL A │ 247,455,256,379 │ 1.42 │ 1418 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ AZN │ AstraZeneca PLC │ 148,465,847,587.12 │ 0.47 │ 1309 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ XOM │ EXXON MOBIL CORP │ 138,784,059,363.77 │ 0.78 │ 4716 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ CVX │ CHEVRON CORP │ 77,783,933,645.44 │ 0.6 │ 4261 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ JNJ │ JOHNSON & JOHNSON │ 64,498,075,844.9 │ 0.76 │ 4603 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ SNDK │ SANDISK CORP │ 58,662,972,096.01 │ 0.65 │ 1172 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ MU │ MICRON TECHNOLOGY INC │ 55,374,569,969.23 │ 0.7 │ 2993 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ AMAT │ APPLIED MATERIALS INC │ 48,790,109,328.41 │ 0.52 │ 2931 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ EEM │ ISHARES MSCI EMERGING MARKET │ 48,211,222,155.7 │ 0.59 │ 1637 │
├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤
│ CAT │ CATERPILLAR INC │ 46,035,710,179.58 │ 0.5 │ 3724 │
└────────┴──────────────────────────────┴────────────────────┴──────────────┴──────────────┘
```
## Why AlphaSMO
- 📊 **13F institutional holdings** — every hedge fund and asset manager's quarterly SEC filings: AUM, positions, and behavioral "personality scores" (concentration, turnover, sector conviction). Read our guide on [What Is a 13F Filing?](https://alphasmo.com/blog/what-is-13f-filing) and [How to Read Institutional Holdings Changes](https://alphasmo.com/blog/how-to-read-institutional-holdings-changes).
- 🕵️ **Insider trading (Form 4 & 144)** — officer/director/10%-owner buys and sells, with a confidence score per ticker. Learn more in [What Is a Form 4 Filing?](https://alphasmo.com/blog/what-is-form-4-filing) and [What Is a Form 144 Filing?](https://alphasmo.com/blog/what-is-form-144-filing).
- 🚀 **Smart money convergence** — the flagship signal: tickers where 13F institutions *and* company insiders are both buying right now.
- 🤖 **Built for AI agents** — an MCP server out of the box, so Claude, ChatGPT, Cursor, or any MCP client can pull real financial data mid-conversation.
- 🆓 **Free anonymous tier** — no signup required to try it; [get a free API key](https://alphasmo.com/developer) any time to raise your rate limit.
## Use cases
```
"What is smart money buying right now?" → alphasmo convergence
"What does Berkshire Hathaway hold?" → alphasmo institutions holdings berkshire-hathaway-inc
"Are insiders buying or selling NVDA?" → alphasmo insider summary NVDA
"Which stocks are institutions dumping?" → alphasmo stocks flows --direction sell
```
Wire the MCP server into Claude Desktop, Claude Code, Cursor, or any MCP client (see [below](#mcp-server)) and ask these in plain English — no code required.
## CLI
```bash
npx alphasmo institutions search "Berkshire"
npx alphasmo stocks get AAPL
npx alphasmo convergence -l 5
```
No install step required — `npx` fetches and runs it. Or install globally:
```bash
npm install -g alphasmo
alphasmo --help
```
### Commands
| Command | What it returns |
|---|---|
| `alphasmo institutions search <query> [-l\|--limit]` | Search 13F institutions by name |
| `alphasmo institutions list [-l\|--limit] [-o\|--offset]` | Paginate the full institution universe (no query) |
| `alphasmo institutions get <slug>` | Full institution detail, sector weights |
| `alphasmo institutions holdings <slug>` | Latest 13F holdings for one institution |
| `alphasmo stocks get <identifier>` | Full stock detail — holder count, flows, top holders (identifier = ticker or CUSIP) |
| `alphasmo stocks flows [-d\|--direction buy\|sell] [-l\|--limit]` | Stocks ranked by net institutional buy/sell flow |
| `alphasmo insider trades <ticker>` | Recent individual Form 4 insider trades for one ticker |
| `alphasmo insider summary <ticker>` | Insider confidence scores (30d/90d) for one ticker |
| `alphasmo convergence [-l\|--limit] [--min-confidence] [--days]` | Tickers where 13F institutions *and* insiders are both buying — the flagship signal |
| `alphasmo mcp` | Start the MCP server over stdio |
Global flags on every command: `--api-key <key>` (env `ALPHASMO_API_KEY`), `--base-url <url>` (env `ALPHASMO_BASE_URL`), `-f`/`--format json|compact|table|csv`, `--json` (shorthand for `--format json`), `--csv` (shorthand for `--format csv`).
**Output format auto-detects your context** — no flag needed in the common case:
- Typed directly in a terminal → a readable table, with numbers comma-formatted (`263,095,703,570`).
- Piped, redirected, or spawned by a script/AI agent (stdout isn't a TTY) → JSON, safe to pipe into `jq` or feed to an agent.
- `--format`/`--json`/`--csv` always override the auto-detection either way.
```bash
alphasmo stocks flows --csv > flows.csv
alphasmo insider trades AAPL --csv | column -s, -t
```
Errors go to stderr with a distinct exit code (`2` not found, `3` auth, `4` rate limit, `5` unexpected response shape, `1` other), so scripts can branch without string-matching.
## Get an API key
Anonymous requests are rate-limited by IP. Sign up and mint a free key at **[alphasmo.com/developer](https://alphasmo.com/developer)**, then:
```bash
alphasmo convergence --api-key ask_live_...
# or
export ALPHASMO_API_KEY=ask_live_...
```
## MCP server
### Option 1: `claude mcp add` (recommended)
If you're using [Claude Code](https://docs.claude.com/claude-code), register the server with one command:
```bash
claude mcp add alphasmo -- npx -y alphasmo@latest mcp
```
Add `-e ALPHASMO_API_KEY=ask_live_...` before the `--` to raise your rate limit. Run `claude mcp list` to confirm it's connected.
### Option 2: manual MCP client config
For Claude Desktop, Cursor, or any other MCP client, add this to your config file directly:
```json
{
"mcpServers": {
"alphasmo": {
"command": "npx",
"args": ["alphasmo", "mcp"],
"env": { "ALPHASMO_API_KEY": "optional-your-key-here" }
}
}
}
```
Both options work anonymously out of the box, at lower rate limits than with a key. Tools exposed: `search_institutions`, `get_institution_profile`, `get_institution_holdings`, `get_stock_overview`, `get_stock_flows`, `get_insider_activity`, `get_smart_money_convergence`.
Full endpoint reference: [alphasmo.com/developer/docs](https://alphasmo.com/developer/docs).
## Programmatic use
```ts
import { AlphasmoClient } from "alphasmo";
const client = new AlphasmoClient(); // no apiKey needed to try it
console.log(await client.getSmartMoneyConvergence({ limit: 5 }));
```
```bash
npm install alphasmo
```
A Python client + MCP server is also available — see [alphasmo.com/developer](https://alphasmo.com/developer) for setup.
## Learn more
- **[alphasmo.com](https://alphasmo.com)** — the full web app: institution profiles, stock screeners, insider-trading leaderboards
- **[alphasmo.com/developer](https://alphasmo.com/developer)** — get a free API key
- **[alphasmo.com/developer/docs](https://alphasmo.com/developer/docs)** — full public API reference
### Educational Guides & SEC Filings Deep Dives
Deepen your understanding of institutional holdings and SEC filing dynamics:
- **[What Is a 13F Filing?](https://alphasmo.com/blog/what-is-13f-filing)** — Beginner's guide to institutional holdings disclosures.
- **[What Is a Form 4 Filing?](https://alphasmo.com/blog/what-is-form-4-filing)** — How insider buying & selling gets reported.
- **[What Is a Form 144 Filing?](https://alphasmo.com/blog/what-is-form-144-filing)** — Understanding SEC pre-sale notices before insider dumps.
- **[13D vs. 13G Beneficial Ownership](https://alphasmo.com/blog/13d-vs-13g-beneficial-ownership)** — Uncovering 5% ownership filings and activist investor intent.
- **[How to Read Institutional Holdings Changes](https://alphasmo.com/blog/how-to-read-institutional-holdings-changes)** — Navigating 13F portfolio changes without being misled by stock splits or option mechanics.
## License
MIT