# cvi-mcp — CVI global equity intelligence for AI assistants

An [MCP](https://modelcontextprotocol.io) server that makes the
[CVI Platform](https://www.computationalvalueinvesting.com/developers) a native tool
for Claude Desktop, Claude Code, Cursor and any MCP-capable assistant. Ask in plain
language — *"the 20 most undervalued stocks worldwide"*, *"Continental's margin of
safety"*, *"what did CVI's model say about NEM on July 15?"* — and the assistant
calls CVI's research engine directly: 25 markets, ~2,900 companies, trailing-twelve-month
valuations, hierarchical model predictions and a point-in-time Time Machine.

Every tool response carries **provenance** — the immutable, checksummed research run
and as-of timestamp behind the numbers — so the assistant can cite exactly where a
figure came from.

## Install

```bash
pip install cvi-mcp
```

## Connect

**Claude Desktop** — add to `claude_desktop_config.json`
(Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "cvi": {
      "command": "cvi-mcp",
      "env": { "CVI_API_KEY": "cvi_live_…" }
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add cvi -e CVI_API_KEY=cvi_live_… -- cvi-mcp
```

Generate a key from your [CVI account](https://www.computationalvalueinvesting.com/account).
Scopes map to plan tiers — see [pricing](https://www.computationalvalueinvesting.com/pricing).

## Tools

| Tool | What it answers | Scope |
|------|-----------------|-------|
| `cvi_screen` | Most undervalued stocks worldwide (filter by market/sector/signal) | `read` |
| `cvi_markets` | Which 25 markets are covered | `read` |
| `cvi_market_rankings` | Ranked securities within one market | `read` |
| `cvi_company` | One company's IDs + scores + valuation + margin of safety | `read` |
| `cvi_time_machine` | The research snapshot recorded for a past date | `research` |
| `cvi_history` | How CVI's view of a company evolved across runs | `research` |
| `cvi_predictions` | Hierarchical model picks with confidence | `models` |
| `cvi_analyze_portfolio` | Exposures, weighted scores, concentration for any holdings | `portfolio` |
| `cvi_platform_status` | Coverage, current research run, service health | — |

## Example conversation

> **You:** Which European industrials look cheapest right now?
> **Claude:** *(calls `cvi_screen(sector="Industrials")`, filters European indices)*
> Fincantieri (FTSE MIB) screens cheapest — undervaluation score 0.92, Buy signal,
> full data confidence — per CVI research run `CVIR20260715224827` (data as of 2026-07-15).

## Development

```bash
pip install -e ".[dev]" && pytest -q     # offline tests, no key needed
```

---
Research and educational use only — not investment advice. Data licensing terms apply.