Metadata-Version: 2.4
Name: neleus-mcp
Version: 0.1.0
Summary: MCP server exposing Neleus Hyperliquid market tools to Claude
Project-URL: Homepage, https://github.com/auralshin/neleus-mcp
Project-URL: Repository, https://github.com/auralshin/neleus-mcp
Project-URL: Documentation, https://auralshin.github.io/neleus/
Project-URL: Bug Tracker, https://github.com/auralshin/neleus-mcp/issues
Author: Neleus Team
License: MIT
Keywords: claude,hyperliquid,mcp,neleus,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: neleus>=0.1.14
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# neleus-mcp

MCP server that exposes [Neleus](https://github.com/auralshin/neleus) Hyperliquid tools to Claude. Gives Claude real-time market data and optional live trading directly from the conversation.

## Tools

### Market tools (no credentials needed)

| Tool | Description |
|---|---|
| `neleus_list_markets` | List markets by scope: perps, all-perps, hip3, spot, hip4 |
| `neleus_analyze_market` | Full TA analysis — RSI, trend, Bollinger bands, support/resistance |
| `neleus_scan_markets` | Rank a bounded set of markets by composite TA score |
| `neleus_get_order_book` | L2 order book snapshot with spread and imbalance |

### Docs tools (no credentials needed)

| Tool | Description |
|---|---|
| `neleus_list_docs` | List the local Neleus documentation pages |
| `neleus_search_docs` | Search the local Neleus docs corpus |
| `neleus_read_doc` | Read a specific Neleus documentation page by route |

### Trading tools (credentials required)

| Tool | Description |
|---|---|
| `neleus_place_limit_order` | Place a limit order |
| `neleus_place_market_order` | Place a market order |
| `neleus_cancel_order` | Cancel an open order by ID |
| `neleus_get_open_orders` | List all open orders |
| `neleus_get_fills` | Fetch recent fill history |

## Installation

Neleus requires the Rust extension built from source. Install Neleus first:

```bash
# In the neleus repo
python3 -m venv .venv
source .venv/bin/activate
pip install maturin
VIRTUAL_ENV=$PWD/.venv .venv/bin/maturin develop --release -m crates/pybridge/Cargo.toml
pip install -e python/
```

Then install neleus-mcp into the same environment:

```bash
pip install neleus-mcp
```

Or for development (from this repo):

```bash
pip install -e .
```

## Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "neleus": {
      "command": "/path/to/.venv/bin/neleus-mcp",
      "env": {
        "HYPERLIQUID_TESTNET": "false"
      }
    }
  }
}
```

For live trading, add credentials:

```json
{
  "mcpServers": {
    "neleus": {
      "command": "/path/to/.venv/bin/neleus-mcp",
      "env": {
        "HYPERLIQUID_SIGNER_PRIVATE_KEY": "0x...",
        "HYPERLIQUID_ACCOUNT_ADDRESS": "0x...",
        "HYPERLIQUID_TESTNET": "false"
      }
    }
  }
}
```

### Claude Code (project-local)

Add to `.claude/settings.json` in your project:

```json
{
  "mcpServers": {
    "neleus": {
      "command": "/path/to/.venv/bin/neleus-mcp"
    }
  }
}
```

No docs configuration needed — the server fetches the manifest from the deployed docs site automatically.

### Environment variables

| Variable | Required | Description |
|---|---|---|
| `HYPERLIQUID_SIGNER_PRIVATE_KEY` | Trading only | Wallet private key (`0x...`) |
| `HYPERLIQUID_ACCOUNT_ADDRESS` | No | Optional; used for delegated-account flows |
| `HYPERLIQUID_TESTNET` | No | `true` to default all tools to testnet |
| `NELEUS_DOCS_URL` | No | Override the manifest URL (default: deployed GitHub Pages) |
| `NELEUS_DOCS_MANIFEST_PATH` | No | Use a local manifest file instead of fetching (offline/dev) |
| `NELEUS_DOCS_MANIFEST_PATH` | No | Path to `docs/assets/ai/page-manifest.json` |

## Usage examples

Once connected, Claude can answer questions like:

- *"What are the top 5 perp markets by TA score right now?"*
- *"Analyze BTC on the 4h timeframe."*
- *"Show me the order book for ETH-PERP."*
- *"List all HIP-3 markets on the flx DEX."*
- *"Search the Neleus docs for database config."*
- *"Read the `cli/market` docs page."*
- *"What are my open orders?"* (requires credentials)
- *"Place a limit buy of 0.001 BTC at 95000."* (requires credentials + explicit confirmation)

## Notes

- All market data is fetched via the Rust Hyperliquid adapter inside `neleus_core`.
- Docs are read locally from the Neleus MkDocs AI manifest (`docs/assets/ai/page-manifest.json`).
- HIP-4 outcome markets are testnet-only — pass `testnet=true` for that scope.
- Trading tools will raise `PermissionError` if credentials are not set.
- Claude will always ask for confirmation before placing or cancelling orders.
