perpbrain-sdk MCP server
Commit Nov 16, 2026Lets an AI client read Hyperliquid market data and run simulated trades with verifiable receipts and owner-defined risk limits.
Also known as PERPBRAIN/perpbrain-sdk
- Stars
- 0
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 16, 2026
- License
- MIT
What is perpbrain-sdk MCP?
perpbrain-sdk lets an AI client read Hyperliquid market data and run simulated trades with verifiable receipts and owner-defined risk limits. It exposes 12 tools, such as markets, order_book, funding.
Summary generated from the project's README
About perpbrain-sdk MCP server
Analyzing Hyperliquid market data and testing trading strategies through simulated environments is what this MCP server enables for developers and AI agents. It provides a way to read perpetual market information, order books, and funding rates without requiring any exchange keys or sensitive credentials. Because it uses the public info endpoint, the setup is entirely keyless and runs locally via stdio.
Users can interact with twelve specific tools, including markets, order_book, and funding_extremes, to gather real-time data. The server features a built-in book simulator that allows for testing decisions with verifiable and reproducible simulation receipts. To manage risk, the system includes owner-defined limits such as conservative, standard, or pro presets, alongside a kill-switch latch to prevent unauthorized or excessive simulated activity. This makes it a safe sandbox for testing logic before moving to live environments.
What you can do with it
- 1Simulate trading decisionsAn AI agent can test a specific market strategy using the book simulator to see how it would have performed.
- 2Verify simulation integrityDevelopers can ensure that simulation results have not been tampered with by checking the cryptographic receipts.
- 3Monitor market metricsUsers can request specific data points like funding rates or order book imbalances to inform their models.
Written from the project's README. Every use case is checked against a quote from it.
perpbrain-sdk MCP tools 12
Detected from the READMEmarketsorder_bookfundingpositionsfeessimulatefunding_extremesbook_imbalanceget_limitstrigger_kill_switchget_cost_breakdownverify_receipt
Configuration
PERPBRAIN_HL_NETWORK
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableperpbrain/perpbrain-sdk is public and reachablegithub.com/perpbrain/perpbrain-sdk ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/perpbrain/perpbrain-sdk ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPERPBRAIN SDK
TypeScript SDK, MCP handler, examples, and receipt verifier for PERPBRAIN: read-only Hyperliquid data, a book simulator, and owner limits for AI agents. Simulation receipts are verified and reproducible: anyone can re-derive a receipt from its inputs and get the same hashes.
This repository has no mainnet order path, no exchange keys, and no publish workflow. Simulation output is labelled SIMULATED. It is not advice.
The PERPBRAIN hosted service and engine are not in this repository. This repository is the public client surface.
What is here
| Path | Role |
|---|---|
sdk/ |
@perpbrain/sdk: public info-endpoint reads, the book simulator, owner limits (conservative, standard, pro), the kill-switch latch, execution-cost breakdown, receipt verifier, and the SVG results card. |
ts/mcp-server/ |
MCP JSON-RPC handler and stdio MCP server (perpbrain-mcp) for the read and simulation tools. It does not accept an order tool. |
server.json |
MCP Registry metadata for io.github.PERPBRAIN/perpbrain-sdk (npm, stdio, no secrets). Optional logo path: docs/assets.md. |
glama.json |
Glama listing maintainer file (claim ownership of the Glama listing). |
Dockerfile |
Slim Node image for Glama and other hosts; stdio entrypoint, non-root user. |
examples/ |
Runnable TypeScript examples on recorded public data. |
verify/web/ |
Browser receipt checker (WebCrypto SHA-256), the same check as the PERPBRAIN verify page. |
fixtures/ |
Recorded public info responses and good and tampered receipt fixtures. No keys, no accounts. |
Requirements
Node 22+ is required (check with node -v). On Node 20 or older the examples and tests stop with node: bad option: --experimental-strip-types; upgrade Node to fix it. On Node 22 a harmless ExperimentalWarning: Type Stripping line is printed. No API key or other secret is needed for anything in this repository.
Install the MCP server
From a fresh clone:
git clone https://github.com/PERPBRAIN/perpbrain-sdk.git
cd perpbrain-sdk/ts/mcp-server && npm ci
cd ../..
node bin/perpbrain-mcp.mjs
To smoke-test it, pipe an initialize request followed by tools/list into the launcher; it should list the 12 tools below.
The launcher starts the stdio MCP server. Live reads use the public Hyperliquid /info endpoint (mainnet by default). Optional: set PERPBRAIN_HL_NETWORK=testnet for testnet.
Equivalent from the repository root after npm ci in ts/mcp-server/:
node bin/perpbrain-sdk.mjs mcp
To work on the TypeScript SDK itself (not required for MCP-only use):
(cd sdk && npm ci && npm run build)
@perpbrain/sdk is 0.1.0-rc1 and marked private in package.json, so it is not on npm yet. npm run build writes ESM and CommonJS builds to sdk/dist.
Examples
Each example runs offline on the files in fixtures/.
Check a receipt. VERIFIED means every hash re-derived from the inputs matches. A tampered fixture prints MISMATCH and names the field.
node --experimental-strip-types examples/verify-receipt.ts fixtures/receipts/good
node --experimental-strip-types examples/verify-receipt.ts fixtures/receipts/tampered-result
Simulate under the Standard preset, then see a looser leverage blocked before a fill is recorded:
node --experimental-strip-types examples/guarded-simulate.ts
Drive the MCP handler with recorded public data. The tool list is read and simulation only, and submit_order is refused:
node --experimental-strip-types examples/mcp-fixtures.ts
MCP server (stdio)
The standalone MCP server uses the official @modelcontextprotocol/sdk over stdio. It is keyless: live reads use the public Hyperliquid /info endpoint only. Simulation uses the vendored book simulator. submit_order and other order tools are refused.
Simulation receipts are verified and reproducible. Owner limits are limits you set; losses are still possible.
Registry metadata lives in server.json (io.github.PERPBRAIN/perpbrain-sdk). For a step-by-step guide aimed at AI coding assistants (for example Cline), see llms-install.md.
MCP tools (12)
Registered tool names, in list order:
| Tool | Purpose |
|---|---|
markets |
List perpetual markets from the public info endpoint. |
order_book |
Read a capped order book and its data age. |
funding |
Read funding, mark, and open interest for one coin. |
positions |
Read positions for one address. |
fees |
Read the address fee rates and their data age. |
simulate |
Simulate a closed-bar decision on a supplied book. Result is SIMULATED. |
funding_extremes |
Z-score of the public hourly funding rate against a trailing window. |
book_imbalance |
Bid depth divided by ask depth inside a public-book band. |
get_limits |
Read the owner limits and the remaining headroom. |
trigger_kill_switch |
Latch the kill switch. A tool call cannot clear it. |
get_cost_breakdown |
Recompute the execution-cost breakdown from a simulation receipt. The result is SIMULATED. |
verify_receipt |
Check a simulation receipt against manifest and inputs bytes. The check is verified and reproducible. |
Claude Desktop
Add a server block (no API keys). Use absolute paths on your machine:
{
"mcpServers": {
"perpbrain": {
"command": "node",
"args": ["/absolute/path/to/perpbrain-sdk/bin/perpbrain-mcp.mjs"],
"env": {
"PERPBRAIN_HL_NETWORK": "mainnet"
}
}
}
}
Cursor
In Cursor Settings → MCP, add a server with the same shape (stdio, no secrets):
{
"mcpServers": {
"perpbrain": {
"command": "node",
"args": ["/absolute/path/to/perpbrain-sdk/bin/perpbrain-mcp.mjs"],
"env": {
"PERPBRAIN_HL_NETWORK": "mainnet"
}
}
}
}
Replace /absolute/path/to/perpbrain-sdk with your clone path. Run cd ts/mcp-server && npm ci once before first use.
Receipt checker (browser)
Serve verify/web/ with any static server and drop the three receipt files on the page.
Using the SDK
import { GuardSession, guardedSimulate, verifyReceipt } from "@perpbrain/sdk";
const session = GuardSession.fromConfig("standard");
// guardedSimulate(...) records a fill only after the owner limits accept it.
// verifyReceipt(receipt, manifestBytes, inputsBytes) returns { status: "VERIFIED" | "MISMATCH", mismatches }.
The read client only talks to the public /info endpoint, with an allowlist of request types. It refuses /exchange.
Owner limits
These are limits you set; losses are still possible. The owner picks a preset when a session starts. Standard is the default. Inside a session a caller can tighten a limit. A looser value is rejected. An MCP tool cannot set, raise, or clear a limit. Reducing or closing a position is never blocked. Details are in docs/guards.md.
| Limit | Conservative | Standard (default) | Pro |
|---|---|---|---|
| Max leverage, before the per-coin rule | 3x | 5x | 10x |
| Per-order cap | Lesser of $10k and 20% of depth | Lesser of $25k and 20% of depth | Lesser of $250k and 20% of depth |
| Daily stop | 3% | 5% | 10% |
| Open positions | 3 | 5 | 15 |
| Max slippage | 25 bps | 50 bps | 100 bps |
| Order rate | 2/s | 5/s | 10/s |
Custom limits are capped at a 25% daily stop, 300 bps slippage, and 50 open positions.
Do not put exchange keys, wallets, or seed phrases in the environment, the repository, or a prompt. Nothing here reads them.
Checks
(cd ts/mcp-server && npm run lint && npm run typecheck && npm test)
(cd sdk && npm run typecheck && npm run build)
ts/mcp-server/node_modules/.bin/tsc -p examples/tsconfig.json
CI runs the same checks plus a pinned gitleaks scan. CI uses no secrets.
Security and contributing
Report a vulnerability as described in SECURITY.md. Contribution rules are in CONTRIBUTING.md.
License
MIT. See LICENSE.
Simulation only. Not advice. No live trading.
perpbrain-sdk MCP questions
What tools does perpbrain-sdk MCP provide?
It exposes 12 tools, including markets, order_book, funding, positions, fees.
Can I place real trades with this MCP server?
No, the server is read-only and simulation-only. It does not accept an order tool and has no mainnet order path.
Do I need an API key to use the server?
No API key or other secret is required to use the repository or the MCP server.
How are simulation results verified?
Simulation receipts are reproducible, meaning anyone can re-derive a receipt from its inputs to verify the hashes.