haruspex-skills

An MCP server for stock analysis, plus Anthropic Skills that build on it — powered by Haruspex.

This repository contains two things:

1. An MCP server — @haruspex-guru/mcp-server, a Model Context Protocol server that exposes the Haruspex stock-analysis API as tools (get_stock_score, get_stock_score_history, get_batch_scores, search_stocks, get_stock_news). Its source and Dockerfile live in mcp-server/, and it is published to npm as @haruspex-guru/mcp-server.
2. A set of Anthropic Agent Skills (in skills/) that build structured trading workflows — single-ticker reads, watchlist scans, thesis checks, a Japanese-language variant — on top of that MCP server.

MCP Server

The MCP server lives in mcp-server/ and is published as @haruspex-guru/mcp-server. It speaks the Model Context Protocol over stdio and exposes five tools:

Run it directly:

npx -y @haruspex-guru/mcp-server

Build from source (Docker):

docker build -t haruspex-mcp mcp-server/   # or build from repo root: docker build -t haruspex-mcp .

The server reads HARUSPEX_API_KEY at runtime for live data; get a key at https://haruspex.guru/settings. The Anthropic Skills below depend on this MCP server for their data — without it installed, the skills detect that, output install instructions, and stop; they will never fabricate analysis.

Skills in this repo

Each skill is a folder containing a SKILL.md with YAML frontmatter, a reference.md for deeper docs, and an examples.md with full example dialogues using real captured data.

Surface support matrix

Compliance & disclaimer

These skills produce analysis, not advice. Every skill is hard-coded with compliance rules that prohibit direct buy/sell/hold recommendations, price predictions, position sizing, and stop-loss/take-profit specifics. Every skill output includes the canonical disclaimer footer.

The full disclaimer language and the rationale behind each compliance rule are in shared/DISCLAIMER.md. Treat that file and the "Compliance rules (NEVER VIOLATE)" sections of each SKILL.md as load-bearing.

Nothing in this repository is investment advice. Haruspex scores are quantitative signals derived from public data, provided for informational purposes only.

Topic dimensions

The Haruspex score is a composite of topic dimensions (e.g. competitors, earnings, supplychain, us_china_official). Plain-English descriptions of all 16 are in shared/DIMENSIONS.md. The scoring methodology itself is proprietary and intentionally not documented here.

Contributing

See CONTRIBUTING.md. The short version:

• Open an issue before opening a PR for non-trivial changes.
• Run bash scripts/validate-skills.sh before submitting.
• Examples must use real captured data from the live API. Fabrication will be rejected.
• Compliance language is non-negotiable.

Eval queries

eval/queries/ contains ~20 trigger-test queries per skill (half should-trigger, half should-not, with cross-skill ambiguity cases). Use them when revising any skill's description field. See eval/README.md for the manual evaluation procedure.

License

MIT. The MCP server and skills (instructions and examples in this repository) are MIT-licensed. The Haruspex scoring algorithm and underlying data are proprietary; access is governed by the Haruspex API Terms of Service. See NOTICE for the full scope statement.

Where this came from

Built for the Haruspex community, inspired by patterns we've seen work in real trader workflows. Submissions to the official anthropics/skills catalog will follow once the skills have a stable shape here.

Quickstart — Claude Code (recommended)

This is the path we test against.

1. Install skills. From this repo:
   Copy & paste — that's itCopy

   git clone https://github.com/Haruspex-guru/haruspex-skills.git
   mkdir -p ~/.claude/skills
   cp -r haruspex-skills/skills/* ~/.claude/skills/

2. Register the MCP server at user scope (works in any project):
   Copy & paste — that's itCopy

   claude mcp add-json --scope user haruspex '{
     "command": "npx",
     "args": ["-y", "@haruspex-guru/mcp-server"],
     "env": { "HARUSPEX_API_KEY": "hrspx_demo_public_REPLACE_ME" }
   }'

   Replace hrspx_demo_public_REPLACE_ME with your real key from https://haruspex.guru.
3. Verify:
   Copy & paste — that's itCopy

   claude mcp list           # haruspex should show ✓ Connected

   Then in a Claude Code session:
   Copy & paste — that's itCopy

   /mcp                      # browse Haruspex tools
   /skills                   # see all 4 haruspex skills (✔ on)

4. Try a query:
   Copy & paste — that's itCopy

   What do you think about NVDA?

   The haruspex-stock-analyst skill auto-triggers, calls the MCP tools, and returns structured analysis with a verifiable share URL.

Quickstart — Claude.ai (web)

1. Enable code execution in Claude.ai if you haven't already (Settings → Capabilities).
2. Package each skill as a ZIP. From this repo:
   Copy & paste — that's itCopy

   cd skills
   for d in */; do (cd "$d" && zip -r "../${d%/}.zip" .); done

   Produces 4 ZIPs in the skills/ directory.
3. Upload each ZIP: claude.ai → Settings → Customize → Skills → "+" → Upload a skill. Repeat for all four.
4. Configure @haruspex-guru/mcp-server via Connectors (the Connectors UI is separate from local Desktop config). Use your Haruspex API key.
5. Try a query in any chat: "What do you think about NVDA?"

Heads-up: skills uploaded to claude.ai are subject to Anthropic's review guidelines for third-party content. "Only install skills from trusted sources" applies — Haruspex skills do not execute arbitrary code, but users should still review the SKILL.md files before installing.

Quickstart — Claude API / SDK

The Claude API supports Agent Skills programmatically. Bundle the skill directories with your request and pass the MCP server configuration alongside. See Anthropic's official Skills API docs for current syntax.

Prerequisites

• A Haruspex API key — sign up at https://haruspex.guru. Never commit your API key to a repository.
• One of: Claude Code, Claude.ai web, or the Claude API.
• Node.js 18+ if you're running @haruspex-guru/mcp-server via npx.

Full per-surface MCP setup details live in shared/MCP_SETUP.md.

Claude Desktop — current limitation

The native Claude Desktop app does not load user-installable filesystem skills as of v0.1.0 of this repo (April 2026). Desktop's skills runtime currently only surfaces a built-in set (docx, pdf, pptx, etc.).

The MCP server side does work in Claude Desktop — see shared/MCP_SETUP.md for claude_desktop_config.json setup. But without a skills runtime, you'd be left calling MCP tools freeform rather than getting the structured workflow these skills enforce.

For Desktop users today: install Claude Code and use it from your terminal, or use claude.ai web with the ZIP upload flow above. Anthropic may add filesystem-skills support to Desktop later; this repo will update when that ships.