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

Quickstart — Claude Code (recommended)

This is the path we test against.

1. Install skills. From this repo:

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):

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

.

3. Verify:

claude mcp list           # haruspex should show ✓ Connected

Then in a Claude Code session:

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

4. Try a query:

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:

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.

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.

Prerequisites

• A Haruspex API key — sign up at . **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`.

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.