{
  "markdown": "# AlphaSMO — The Ultimate Smart Money API for AI\n\n[![npm version](https://img.shields.io/npm/v/alphasmo.svg)](https://www.npmjs.com/package/alphasmo)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**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.).\n\nNo signup, no API key, no setup — try it right now:\n\n```bash\nnpx alphasmo stocks flows --limit 10\n```\n**Example output:**\n```text\n┌────────┬──────────────────────────────┬────────────────────┬──────────────┬──────────────┐\n│ ticker │ issuer                       │ net flow (USD)     │ avg weight % │ institutions │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ BRK-A  │ BERKSHIRE HATHAWAY INC-CL A  │ 247,455,256,379    │ 1.42         │ 1418         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ AZN    │ AstraZeneca PLC              │ 148,465,847,587.12 │ 0.47         │ 1309         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ XOM    │ EXXON MOBIL CORP             │ 138,784,059,363.77 │ 0.78         │ 4716         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ CVX    │ CHEVRON CORP                 │ 77,783,933,645.44  │ 0.6          │ 4261         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ JNJ    │ JOHNSON & JOHNSON            │ 64,498,075,844.9   │ 0.76         │ 4603         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ SNDK   │ SANDISK CORP                 │ 58,662,972,096.01  │ 0.65         │ 1172         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ MU     │ MICRON TECHNOLOGY INC        │ 55,374,569,969.23  │ 0.7          │ 2993         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ AMAT   │ APPLIED MATERIALS INC        │ 48,790,109,328.41  │ 0.52         │ 2931         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ EEM    │ ISHARES MSCI EMERGING MARKET │ 48,211,222,155.7   │ 0.59         │ 1637         │\n├────────┼──────────────────────────────┼────────────────────┼──────────────┼──────────────┤\n│ CAT    │ CATERPILLAR INC              │ 46,035,710,179.58  │ 0.5          │ 3724         │\n└────────┴──────────────────────────────┴────────────────────┴──────────────┴──────────────┘\n```\n## Why AlphaSMO\n\n- 📊 **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).\n- 🕵️ **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).\n- 🚀 **Smart money convergence** — the flagship signal: tickers where 13F institutions *and* company insiders are both buying right now.\n- 🤖 **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.\n- 🆓 **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.\n\n## Use cases\n\n```\n\"What is smart money buying right now?\"        → alphasmo convergence\n\"What does Berkshire Hathaway hold?\"            → alphasmo institutions holdings berkshire-hathaway-inc\n\"Are insiders buying or selling NVDA?\"          → alphasmo insider summary NVDA\n\"Which stocks are institutions dumping?\"        → alphasmo stocks flows --direction sell\n```\n\nWire 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.\n\n## CLI\n\n```bash\nnpx alphasmo institutions search \"Berkshire\"\nnpx alphasmo stocks get AAPL\nnpx alphasmo convergence -l 5\n```\n\nNo install step required — `npx` fetches and runs it. Or install globally:\n\n```bash\nnpm install -g alphasmo\nalphasmo --help\n```\n\n### Commands\n\n| Command | What it returns |\n|---|---|\n| `alphasmo institutions search <query> [-l\\|--limit]` | Search 13F institutions by name |\n| `alphasmo institutions list [-l\\|--limit] [-o\\|--offset]` | Paginate the full institution universe (no query) |\n| `alphasmo institutions get <slug>` | Full institution detail, sector weights |\n| `alphasmo institutions holdings <slug>` | Latest 13F holdings for one institution |\n| `alphasmo stocks get <identifier>` | Full stock detail — holder count, flows, top holders (identifier = ticker or CUSIP) |\n| `alphasmo stocks flows [-d\\|--direction buy\\|sell] [-l\\|--limit]` | Stocks ranked by net institutional buy/sell flow |\n| `alphasmo insider trades <ticker>` | Recent individual Form 4 insider trades for one ticker |\n| `alphasmo insider summary <ticker>` | Insider confidence scores (30d/90d) for one ticker |\n| `alphasmo convergence [-l\\|--limit] [--min-confidence] [--days]` | Tickers where 13F institutions *and* insiders are both buying — the flagship signal |\n| `alphasmo mcp` | Start the MCP server over stdio |\n\nGlobal 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`).\n\n**Output format auto-detects your context** — no flag needed in the common case:\n- Typed directly in a terminal → a readable table, with numbers comma-formatted (`263,095,703,570`).\n- 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.\n- `--format`/`--json`/`--csv` always override the auto-detection either way.\n\n```bash\nalphasmo stocks flows --csv > flows.csv\nalphasmo insider trades AAPL --csv | column -s, -t\n```\n\nErrors 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.\n\n## Get an API key\n\nAnonymous requests are rate-limited by IP. Sign up and mint a free key at **[alphasmo.com/developer](https://alphasmo.com/developer)**, then:\n\n```bash\nalphasmo convergence --api-key ask_live_...\n# or\nexport ALPHASMO_API_KEY=ask_live_...\n```\n\n## MCP server\n\n### Option 1: `claude mcp add` (recommended)\n\nIf you're using [Claude Code](https://docs.claude.com/claude-code), register the server with one command:\n\n```bash\nclaude mcp add alphasmo -- npx -y alphasmo@latest mcp\n```\n\nAdd `-e ALPHASMO_API_KEY=ask_live_...` before the `--` to raise your rate limit. Run `claude mcp list` to confirm it's connected.\n\n### Option 2: manual MCP client config\n\nFor Claude Desktop, Cursor, or any other MCP client, add this to your config file directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"alphasmo\": {\n      \"command\": \"npx\",\n      \"args\": [\"alphasmo\", \"mcp\"],\n      \"env\": { \"ALPHASMO_API_KEY\": \"optional-your-key-here\" }\n    }\n  }\n}\n```\n\nBoth 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`.\n\nFull endpoint reference: [alphasmo.com/developer/docs](https://alphasmo.com/developer/docs).\n\n## Programmatic use\n\n```ts\nimport { AlphasmoClient } from \"alphasmo\";\n\nconst client = new AlphasmoClient(); // no apiKey needed to try it\nconsole.log(await client.getSmartMoneyConvergence({ limit: 5 }));\n```\n\n```bash\nnpm install alphasmo\n```\n\nA Python client + MCP server is also available — see [alphasmo.com/developer](https://alphasmo.com/developer) for setup.\n\n## Learn more\n\n- **[alphasmo.com](https://alphasmo.com)** — the full web app: institution profiles, stock screeners, insider-trading leaderboards\n- **[alphasmo.com/developer](https://alphasmo.com/developer)** — get a free API key\n- **[alphasmo.com/developer/docs](https://alphasmo.com/developer/docs)** — full public API reference\n\n### Educational Guides & SEC Filings Deep Dives\n\nDeepen your understanding of institutional holdings and SEC filing dynamics:\n\n- **[What Is a 13F Filing?](https://alphasmo.com/blog/what-is-13f-filing)** — Beginner's guide to institutional holdings disclosures.\n- **[What Is a Form 4 Filing?](https://alphasmo.com/blog/what-is-form-4-filing)** — How insider buying & selling gets reported.\n- **[What Is a Form 144 Filing?](https://alphasmo.com/blog/what-is-form-144-filing)** — Understanding SEC pre-sale notices before insider dumps.\n- **[13D vs. 13G Beneficial Ownership](https://alphasmo.com/blog/13d-vs-13g-beneficial-ownership)** — Uncovering 5% ownership filings and activist investor intent.\n- **[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.\n\n## License\n\nMIT\n",
  "bytes": 9745,
  "sha": "bd1488501cfd0d50990fd4f68c6b7fe2dcfdf4b4862cbe90f5fd0d2f3b9632eb",
  "repo_slug": "alphasmo/alphasmo-tools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alphasmo_alphasmo_tools_5c503e17/readme"
}