algochains-library-mcp 0.1.0

MCP server for Claude Desktop: natural-language market research and strategy backtesting with the AlgoChains library.

AlgoChains Library MCP

Ask market-research and trading-strategy questions in plain English, and let Claude pull data with AlgoChains, backtest strategies, and return interactive charts inline — built for Claude Desktop via the Model Context Protocol.

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.
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).

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.
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:

{
  "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

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.