Metadata-Version: 2.4
Name: algochains-library-mcp
Version: 0.1.0
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 — paste this to Claude)

1. Get your API key at [https://algochains.ai](https://algochains.ai).
2. Copy the **entire block below**, replace `YOUR_API_KEY_HERE` with your key, and paste it to
   a Claude that can run commands on your computer (Claude Code, or Claude Desktop with
   file/terminal access).

```text
Please install the AlgoChains MCP server into my Claude Desktop. Follow these steps
exactly and carefully:

My AlgoChains API key is: YOUR_API_KEY_HERE

0. If the key above still literally says "YOUR_API_KEY_HERE", STOP and tell me to
   replace it with my real API key from https://algochains.ai before continuing.

1. Check whether the `uv` tool is installed (run `uv --version`). If it is missing,
   install it:
   - macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh
   - Windows:      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   Then verify `uv --version` works (open a fresh shell or use its full install path if
   needed — note the absolute path to the uvx executable if it is not on PATH).

2. Pre-download the server so Claude Desktop's first launch is fast: run
   `uvx --python 3.12 algochains-library-mcp --version`
   and wait for it to finish (the first run downloads a few hundred MB — this can take
   several minutes; that is normal). It must print a version number.

3. Open my Claude Desktop config file, creating it (and its folder) if it does not exist:
   - macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
   - Windows: %APPDATA%\Claude\claude_desktop_config.json

4. Merge the following server entry into the "mcpServers" object WITHOUT removing or
   modifying any servers already there. If the file is empty or missing, create it with
   exactly this content. If an "algochains" entry already exists, update it in place.
   Preserve valid JSON (no trailing commas, no comments):

   {
     "mcpServers": {
       "algochains": {
         "command": "uvx",
         "args": ["--python", "3.12", "algochains-library-mcp"],
         "env": {
           "ALGOCHAINS_API_KEY": "YOUR_API_KEY_HERE"
         }
       }
     }
   }

   Use my real API key from the top of this message as the ALGOCHAINS_API_KEY value.
   If step 1 showed that uvx is not on the system PATH, use the absolute path to the
   uvx executable as "command" instead of "uvx".

5. Validate that the final file parses as JSON, show me the resulting "algochains"
   entry (mask the middle of the API key), and confirm no other entries were changed.

6. Tell me to 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 AlgoChains tools will
   then appear under the tools icon in the chat box.

Do not do anything beyond these steps.
```

### Manual install

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
2. Pre-download the server (first run takes a few minutes): `uvx --python 3.12 algochains-library-mcp --version`
3. Edit your Claude Desktop config —
   macOS `~/Library/Application Support/Claude/claude_desktop_config.json`,
   Windows `%APPDATA%\Claude\claude_desktop_config.json` — and merge in:

```json
{
  "mcpServers": {
    "algochains": {
      "command": "uvx",
      "args": ["--python", "3.12", "algochains-library-mcp"],
      "env": {
        "ALGOCHAINS_API_KEY": "your_key_here"
      }
    }
  }
}
```

4. Fully quit (Cmd+Q / tray-quit) and reopen Claude Desktop.

**Troubleshooting**
- *"spawn uvx ENOENT" / server won't start*: Desktop apps don't see your shell PATH — put the
  absolute path to `uvx` (usually `~/.local/bin/uvx`, Windows `%USERPROFILE%\.local\bin\uvx.exe`)
  in `"command"`.
- *First launch times out*: run `uvx --python 3.12 algochains-library-mcp --version` in a
  terminal once (downloads the environment), then restart Desktop.
- *"ALGOCHAINS_API_KEY is not set"*: check the `env` block in the config entry, then fully
  restart Desktop.
- *Python errors on install*: the server needs Python 3.10–3.12 — that is why `--python 3.12`
  is in the args; uv downloads that interpreter automatically if missing. Keep it.
- *Updating*: paste "please update the algochains MCP server" to Claude — it runs
  `uvx --python 3.12 algochains-library-mcp@latest --version`, then fully restart Desktop.

## 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
> 3× ATR trailing stop, force-exit at 12:00 ET, over the past 3 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

- Research code and backtests run in **throwaway temp dirs**; a backtest's raw CSVs sit in a
  per-name temp dir that is **auto-deleted ~12h after the run**.
- Each completed backtest also saves two small files **for you** to
  `~/Documents/AlgoChains/comparisons/<run-name>/`: the exact strategy script that ran and its
  `round_trips.csv` — so you can compare runs later (override 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).

## Development

```bash
git clone <repo> && cd mcp_algochains
uv venv && uv pip install -e .
mkdir -p ~/.algochains && echo "ALGOCHAINS_API_KEY=your_key_here" > ~/.algochains/.env

python -m algochains_library_mcp                                # raw stdio
mcp dev src/algochains_library_mcp/server.py                    # MCP Inspector
```

The server reads its API key from the process environment first (Claude Desktop's `env` block),
falling back to `~/.algochains/.env`. A project-local `.env` is **no longer read** — early
testers should move their key. Build and publish with `uv build` / `uv publish`.
