Metadata-Version: 2.4
Name: prysmatic-mcp
Version: 0.1.0
Summary: MCP server exposing the Prysmatic REST API (wallets + tokens) as tools.
Project-URL: Homepage, https://prysmatic-sol.xyz
Project-URL: Documentation, https://docs.prysmatic-sol.xyz
Author-email: eserya <eserya77@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,mcp,model-context-protocol,prysmatic,solana
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# Prysmatic MCP

An [MCP](https://modelcontextprotocol.io) server that exposes the Prysmatic REST
data API (wallets + tokens) as tools, so an MCP client like Claude can query your
tracked-wallet data directly. It's a thin client over the public API — every call
authenticates with **your API key** and spends credits exactly like a REST call.

The live WebSocket feed is intentionally **not** exposed (MCP tools are
request/response, not streaming).

## Tools

| Tool | REST endpoint | What it returns |
|------|---------------|-----------------|
| `list_wallets(page=1)` | `GET /wallets` | Tracked wallets (W{n}), 25/page |
| `wallet_metrics(alias)` | `GET /wallets/{alias}/metrics` | Full metrics for one wallet |
| `wallet_holdings(alias)` | `GET /wallets/{alias}/holdings` | Tokens the wallet currently holds |
| `tokens_held(min_wallets=2, page=1)` | `GET /tokens/held` | Tokens co-held by ≥ N wallets |
| `token_swaps(mint, aggregate=False, tracked_only=True)` | `GET /tokens/{mint}/swaps` | Tracked-wallet swaps on a token |

## Requirements

- Python ≥ 3.10
- A Prysmatic **API key** (get one from the dashboard and load credits).

## Add to Claude

Pick one of the three. All end with the same `claude mcp add` shape; the only
difference is how the `prysmatic-mcp` command is provided.

### 1. From GitHub, no install (recommended) — needs [uv](https://docs.astral.sh/uv/)

`uvx` fetches and runs the package on demand, so there's nothing to install or
keep updated:

```
claude mcp add prysmatic -e PRYSMATIC_API_KEY=<your_key> -- \
  uvx --from "git+https://github.com/eserya77/prysmatic.git#subdirectory=prysmatic-mcp" prysmatic-mcp
```

### 2. Install from GitHub with pipx

```
pipx install "git+https://github.com/eserya77/prysmatic.git#subdirectory=prysmatic-mcp"
claude mcp add prysmatic -e PRYSMATIC_API_KEY=<your_key> -- prysmatic-mcp
```

### 3. From a local clone

```
cd prysmatic-mcp
pip install .
claude mcp add prysmatic -e PRYSMATIC_API_KEY=<your_key> -- prysmatic-mcp
```

To point at a non-production API, also pass `-e PRYSMATIC_API_BASE=<url>`.

## Configuration

| Env var | Required | Default |
|---------|----------|---------|
| `PRYSMATIC_API_KEY` | yes | — |
| `PRYSMATIC_API_BASE` | no | `https://api.prysmatic-sol.xyz` |

## Errors

Tools return readable errors instead of crashing: `401` (bad/missing key),
`402` (out of credits — top up at the dashboard), `404` (e.g. unknown wallet),
and unreachable-API cases.
