Metadata-Version: 2.4
Name: algochains-library-mcp
Version: 0.1.2
Summary: MCP server for Claude Desktop: natural-language market research and strategy backtesting with the AlgoChains library.
Project-URL: Homepage, https://algochains.ai
Project-URL: Documentation, https://algochains.ai/docs/mcp
Author-email: AlgoChains <roo@algochains.io>
License-Expression: MIT
License-File: LICENSE
Keywords: algochains,backtesting,claude,mcp,trading
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.10
Requires-Dist: algochains>=1.0b3
Requires-Dist: anyio>=4
Requires-Dist: matplotlib>=3.8
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: mplfinance>=0.12
Requires-Dist: pillow>=10
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# AlgoChains Library MCP

Ask market-research and trading-strategy questions in plain English, and let Claude pull
data with [AlgoChains](https://algochains.ai), backtest strategies, and return **interactive
charts inline** — built for [Claude Desktop](https://claude.ai/download) via the
[Model Context Protocol](https://modelcontextprotocol.io).

No coding required: describe the strategy, get a full backtest dashboard back in the chat.

## Install (easiest — one click)

1. Get your API key at [https://algochains.ai](https://algochains.ai).
2. Download the extension: [**algochains-library-mcp.mcpb**](https://algochains.ai/mcp/algochains-library-mcp.mcpb).
3. Double-click the downloaded file (or in Claude Desktop: **Settings → Extensions → Install
   extension…** and pick it). Claude Desktop shows an install dialog — paste your API key
   into the **AlgoChains API Key** field and confirm.
4. Fully quit Claude Desktop (**Cmd+Q** on macOS / quit from the system tray on Windows —
   closing the window is not enough) and reopen it.

The first launch downloads the Python environment (a few hundred MB) — it can take several
minutes and Claude Desktop may report the server disconnected once; it recovers on the next
launch. The AlgoChains tools then appear under the tools icon in the chat box.


## Example asks

Research:
> *"For crypto, pick a highly-traded coin and show trading hours in 30-min bins over the last
> 3 months. Highlight the busiest hours and shade market opens for London (blue), China (red),
> Brazil (green), with NYSE as the base case."*

Build & backtest:
> *"Build an opening-range-breakout on SPY — range = first 10 min of the NY session, relaxed
> 2.5% trailing stop loss, force-exit at 12:00 ET, over the past 2 months."*

## What it does

| Kind     | Name                          | What it does                                                                 |
|----------|-------------------------------|------------------------------------------------------------------------------|
| resource | `algochains://agents-guide`   | The library's `AGENTS.md` — API, symbols, resolutions, examples (plus the server's determinism rules). |
| tool     | `research_query`              | Historical OHLCV for one symbol **or a list** — a quick look (wraps `algochains.research_query`). |
| tool     | `run_python`                  | Run Python in a temp dir; any matplotlib figure is returned inline (themed). |
| tool     | `build_report`                | Run analysis cells in a temp dir; charts inline + report as markdown text.   |
| tool     | `build_algorithm`             | Write a `bt.Strategy` and backtest it **in the background**; keeps the CSVs in a per-name temp dir (no plotting). |
| tool     | `make_backtest_dashboard`     | Render the run (**waits if it's still running**): fast matplotlib PNG inline + a React+Recharts interactive artifact. |
| tool     | `send_signal`                 | Propagate a live trade signal (requires `SIGNAL_SECRET`; off by default).    |

Claude reads the resource to ground itself in the library, then uses the tools to answer.

Backtesting is two steps, mirroring research → `build_report`:
1. `build_algorithm(name, ...)` launches the backtest **in the background** (Backtrader is slow —
   long or multi-symbol runs take minutes) and returns quickly with `state:"done"` or `"running"`.
2. `make_backtest_dashboard(name)` waits for the run if needed, then renders a matplotlib PNG
   inline plus `artifact_jsx` — a React+Recharts component Claude drops into an artifact for an
   interactive dashboard (candlestick equity, drawdown, rolling Sharpe, per-trade P&L, round trips).

### What's written to disk (and why)

Almost nothing, and nothing hidden. Research code and backtests run in **throwaway temp
folders** that clean themselves up — a backtest's raw CSVs stick around for ~12 hours in case
you want to inspect them, then they're deleted automatically.

The one thing that's kept: **every completed backtest leaves you a receipt.** Three small
files land in `~/Downloads/AlgoChains/comparisons/<run-name>/` (or `~/Desktop/…` if you have
no Downloads folder):

- **`strategy.py`** — the *exact* code that ran. Not a description of your strategy, the
  literal script that produced the numbers you're looking at.
- **`round_trips.csv`** — every trade it made: entries, exits, P&L.
- **`dashboard.png`** — the dashboard image itself, so the picture of the results survives
  along with the numbers. (not including the trades at the bottom for now, soon to come)

Here's why that matters. A chat scrolls away, but a trading result you might act on shouldn't.
When Claude tells you a strategy returned +12%, these files are your proof of *what* returned
+12% — so next week you can reread the logic, diff two variants of a strategy to see exactly
what changed, or hand the script to someone else to reproduce your result. Without them, "the
backtest I ran last Tuesday" would be a memory; with them it's a folder. And because the
dashboard is saved too, you can simply ask Claude *"show me the dashboard for `<run-name>`
again"* in any later chat — even after the run's working data has long been cleaned up.

Nothing else is saved, the files are a few KB per run, re-running a name simply overwrites
its folder, and deleting any of it is always safe. (Power users can move the location with
`ALGOCHAINS_LIBRARY_MCP_COMPARISONS_DIR`.)

> `run_python`, `build_report`, and `build_algorithm` execute model-written Python locally on
> your machine — that's how Desktop (no code execution of its own) does the analysis. Only
> connect this server in an environment you trust.

## Notes

- Symbol formats: Forex `EUR-USD`, Stocks `AAPL`, Crypto `BTC-USD`.
- **Multiple symbols:** `research_query` and `build_algorithm` accept a **list** of symbols as
  well as a single string. Multi-symbol backtests use the `('symbols', [])` param and
  `self.datas[i]` (see the agents-guide "Multi-asset" section); the equity curve is the true
  combined portfolio value.
- Resolutions: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`. Databases: `Forex`, `Stocks`, `Crypto`.
- Charts use a shared matplotlib/mplfinance theme; the interactive dashboard is React+Recharts
  (Plotly and other CDN-loaded libraries fail in Desktop's artifact sandbox — Recharts is bundled).


