Metadata-Version: 2.4
Name: sharpe-mcp
Version: 1.1.2
Summary: MCP server for Sharpe crypto derivatives and market data API
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: fastmcp<3,>=2.14.2
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Sharpe MCP Server + CLI

Crypto derivatives and market data for AI agents and terminals. Built with [FastMCP](https://github.com/jlowin/fastmcp).

21 tools, 5 resources, 2 prompts for the MCP server. 18 commands for the CLI. Covers funding rates, futures, options, arbitrage, narratives, ecosystems, memecoins, news, and more across 20+ exchanges.

## Quick Start

### MCP Server (for AI agents)

No install needed. Use `uvx` to always run the latest version:

```json
{
  "mcpServers": {
    "sharpe": {
      "command": "uvx",
      "args": ["sharpe-mcp"],
      "env": {
        "SHARPE_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

**Claude Desktop:** Add the above to `claude_desktop_config.json`

**Claude Code:** `claude mcp add sharpe -- uvx sharpe-mcp`

**Cursor:** Add the above to `.cursor/mcp.json`

### CLI (for terminals)

Run ephemerally with `uvx` or install persistently so the `sharpe` binary stays on your PATH.

```bash
# Run without installing (always latest)
uvx --from sharpe-mcp sharpe market

# Persistent install (pick one)
uv tool install sharpe-mcp        # recommended
pipx install sharpe-mcp           # alternative
pip install sharpe-mcp            # inside a venv

sharpe market
```

The `--from sharpe-mcp` flag is needed only for `uvx` — the CLI entry point is `sharpe` but the package is named `sharpe-mcp`. Persistent installers put both `sharpe` and `sharpe-mcp` on your PATH directly.

### Without an API key

Both the MCP server and CLI work without an API key by falling back to free public endpoints. No signup required. Add a key later for higher rate limits.

## MCP Tools (21)

### Composite (synthesize multiple data sources)
- `analyze_coin` — Funding + OI + IV + prediction for one coin
- `market_briefing` — Market overview + narratives + funding summary
- `find_opportunities` — Spot-perp + cross-exchange arb + funding highlights

### Derivatives
- `get_funding_rates` — Perpetual funding rates across 13+ exchanges
- `get_futures_data` — 19 chart types: OI, volume, liquidations, basis, term structure
- `get_futures_coins` — Available coins with capability flags
- `get_options_data` — 22 chart types: IV, Greeks, GEX, vol surface, flow
- `get_derivatives_overview` — Market-wide OI, weighted funding, top coins

### Market Data
- `get_heatmap` — Market heatmap (coins, narratives, ecosystems)
- `get_correlation_matrix` — Crypto + TradFi correlation matrix
- `get_market_overview` — Market cap, BTC dominance, Fear & Greed, gainers/losers
- `get_price_prediction` — AI price predictions with signal breakdowns
- `search_market_cap` — Search coins by name or ticker
- `get_gem_finder` — Low-cap high-potential token discovery
- `get_news` — Aggregated crypto news feed

### Arbitrage
- `get_arbitrage_spot_perp` — Spot-perp basis trade opportunities
- `get_arbitrage_cross_exchange` — Cross-exchange funding rate arb

### Categories
- `get_narratives` — 22 crypto narratives (L1, DeFi, AI, RWA, etc.)
- `get_ecosystems` — 23 blockchain ecosystems (ETH, SOL, ARB, etc.)
- `get_memecoins` — 17 memecoin categories (Dog, Cat, AI, Political, etc.)

### System
- `get_api_coverage` — Available data products, exchanges, timeframes

## CLI Commands (18)

```
sharpe market          # Market overview
sharpe briefing        # Daily composite briefing
sharpe watch market    # Live auto-refresh (30s)
sharpe funding         # Funding rates
sharpe futures <chart> # Futures chart data
sharpe options <chart> # Options analytics
sharpe arb spot-perp   # Arbitrage opportunities
sharpe narratives      # Narrative rotation
sharpe ecosystems      # Ecosystem analytics
sharpe memecoins       # Memecoin narratives
sharpe news            # Crypto news feed
sharpe search <query>  # Search coins
sharpe gems            # Low-cap discovery
sharpe predict         # Price predictions
sharpe doctor          # Self-diagnosis
sharpe login           # Save API key
sharpe coverage        # Available data products
sharpe coins           # Futures coin list
```

All commands support `--json` and `--csv` for scripting. Colors auto-disable when piped.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SHARPE_API_KEY` | No | (none) | API key for higher rate limits |
| `SHARPE_API_URL` | No | `https://api.sharpe.ai` | Base URL for v1 API |
| `SHARPE_FREE_URL` | No | `https://www.sharpe.ai` | Base URL for free API |

## Development

```bash
cd packages/mcp-server-python
pip install -e .
fastmcp dev server.py    # MCP server with inspector
sharpe doctor            # CLI self-test
```

## Links

- [MCP Server docs](https://www.sharpe.ai/docs/mcp-server)
- [CLI docs](https://www.sharpe.ai/docs/cli)
- [API docs](https://www.sharpe.ai/docs)
- [API playground](https://www.sharpe.ai/docs/api-reference)
