MangroveAI

mangrove-agent

Mangrove gives trading agents guardrails. A local MCP server (Model Context Protocol) and provider agnostic plugin with built-in risk management on every order: circuit breakers, automatic risk-based position sizing, and automatically generated stop-loss and take-profit orders.

Built on the Mangrove API, with a REST API alongside. FastAPI + MCP. Strategies are authored and backtested on MangroveAI; this agent supplies the clock, local custody and execution, and a full audit trail.

Kraken and Robinhood venues, and DEX execution via 1inch across 10 EVM chains

---

What this is

mangrove-agent is an open-source local client for Mangrove services. It gives an AI client (Claude Code, Codex, Grok Build, Perplexity Computer, or any MCP client) local tools and access to configured hosted services. Credential and wallet custody depends on the selected workflow:

• Author and test strategies. The agent turns a goal such as "momentum on ETH" into a backtested strategy by calling the MangroveAI API. Strategy building, backtesting, signals, market data and the knowledge base all live in MangroveAI; the agent forwards those tools and keeps no copy of them.
• Paper trade. A paper schedule runs on a clock the agent supplies, while MangroveAI owns the strategy, balances, positions and trades. No funds are at risk.
• Use the supported execution workflows. For local DEX execution, the agent signs transactions on the user's machine. Kraken BYOK keeps its API key local; Kraken OAuth is a separate connection where Mangrove holds the authorized grant. Robinhood uses its documented broker connection. Mangrove-owned execution software enforces deterministic risk management based on live market and account conditions. External AI clients and SDKs request operations and preserve Mangrove's decisions, audit details, and errors; they do not replace its risk policy.
• Keep an audit trail. Local evaluations, DEX swaps and confirmed Robinhood fills are logged to a local SQLite database. Kraken orders are not added to the local trade log.

The agent exposes the same capabilities two ways: an MCP endpoint at http://127.0.0.1:9080/mcp/ and a REST API under /api/v1/agent/. MangroveAI also runs its own hosted MCP server at https://api.mangrovedeveloper.ai/mcp/.

You pay for MangroveAI access with a free API key from https://mangrovedeveloper.ai, or per call in USDC with x402 (no signup). More for agent builders: https://mangrove.ai/agents/ and https://mangrove.ai/llms.txt. Full platform documentation and the trading knowledge base are at https://mangrove.io/docs (knowledge base: https://mangrove.io/knowledge-base); the agent's kb_search tool queries the same corpus.

Choose an install path

Every path runs the same agent. Use one path per machine: the agent listens on 127.0.0.1:9080, so a plugin install and a clone cannot run side by side on that port.

Install with an AI client

One-step Claude Code install (Claude Code 2.1.275 or later):

/plugin install mangrove-agent --marketplace MangroveTechnologies/mangrove-agent

Tell Claude Code, Codex, Grok Build or Perplexity Computer:

Install https://github.com/MangroveTechnologies/mangrove-agent and follow its AI client installation instructions.

The client installs the server in its own execution environment, loads the shared agent instructions, discovers the tools and calls the free status tool before it reports success. The user guide covers installation, choosing the agent's name, coming back later and switching clients. The installing agent follows Install from an agent. Perplexity Computer uses the provided command client and needs no Perplexity Project, custom cloud connector or extra desktop app.

Connect any MCP client (paste-ready config)

Once the agent is running from any install path above, point an MCP client at it with this mcpServers block (the same file ships at the repo root as .mcp.json.example; Claude Code reads it as .mcp.json in the project root, and other clients take the block in their own config file, see AI client setup):

{

"mcpServers": { "mangrove-agent": { "type": "http", "url": "http://127.0.0.1:9080/mcp/", "headers": { "X-API-Key": "REPLACE_WITH_API_KEYS_FROM_server/src/config/local-config.json" } } } }

The API key is written to server/src/config/local-config.json by setup.sh; the agent listens on loopback only.

The agent's shared identity and operating instructions live in SAGE.md. On first run the agent asks what to name itself and saves that choice locally for every client; there is no default personal name. AGENTS.md points Codex and compatible clients to SAGE.md, and CLAUDE.md imports it for Claude Code. Launch helpers, MCP configuration templates and the instruction bundle for hosts without file access are in AI client setup. Tool access is configured and verified separately for each client.

Install with setup.sh (sign-in, API key or x402)

Clone the repository and run ./scripts/setup.sh. Choose an existing MangroveAI API key, browser sign-in (OAuth), or wallet payments (x402, no signup). Browser sign-in requires the OAuth-enabled backend and currently supports a restricted tool catalog; see sign-in setup and limitations. The script protects local access, starts the agent and registers Claude when its CLI is available. For x402, a final menu prints wallet steps for you to run yourself; it never automatically creates/imports a wallet or pays. See the complete setup and wallet flow.

SETUP.md walks through installing these step by step on macOS and Windows.

Quick start: clone and run setup.sh

git clone https://github.com/MangroveTechnologies/mangrove-agent.git mangrove-agent

cd mangrove-agent ./scripts/setup.sh

One command selects API-key or x402 access, creates .venv, installs dependencies, starts the agent in the background, registers it with Claude Code when the claude CLI is present, and verifies authenticated local access. A first run can take a few minutes. Reruns preserve configuration and local state and restart the server only when code or configuration changed. Connecting another client to a running agent does not need a rerun.

When it finishes:

• The agent runs at http://127.0.0.1:9080. Its process ID is in agent-data/bare.pid and its log is agent-data/bare.log.
• setup.sh has run scripts/verify_quickstart.sh, which checks authenticated local access, scheduler readiness and that the onboarding tools are discoverable.
• Claude registration is saved when the CLI is available and you did not pass --no-mcp. Other clients use the command client or their own MCP connection.

After setup, continue with your chosen client using the user guide. For Claude, run the command displayed at the end of setup—it changes to your checkout folder and launches claude. In x402 mode, complete the guided payment-wallet setup before requesting paid data or backtests. API-key users can paper-trade without a payment wallet. Simulated trades do not make upstream API calls free. Continue with your client using the user guide. Claude users can run ./scripts/chat.sh for a session with shell and file tools disabled and only the Mangrove MCP server; see restricted chat. In x402 mode, finish the printed payment-wallet steps before you request paid data or backtests (details). With an API key you can paper trade without a payment wallet. Paper trades are simulated, but the upstream data and evaluation calls behind them still count against your API-key allowance or cost x402 payments.

./scripts/