# etoro-mcp

Read-only remote MCP server exposing eToro portfolio data (positions, P&L,
balances, watchlists, closed trade history) as tools, so it can be registered
as a custom connector in Claude (claude.ai chat, not just an editor). Runs on
Cloudflare Workers over Streamable HTTP.

This is a personal, single-user tool. It never places, modifies, or closes a
trade — only `GET` requests against eToro's API.

## Prerequisites

- Node.js (recent LTS)
- A [Cloudflare](https://dash.cloudflare.com) account (for `wrangler dev` and
  eventual deployment)
- eToro API credentials (`x-api-key` / `x-user-key`) from
  [api-portal.etoro.com](https://api-portal.etoro.com)

Install dependencies:

```bash
npm install
```

### About Wrangler

This project deploys to [Cloudflare Workers](https://developers.cloudflare.com/workers/),
and [Wrangler](https://developers.cloudflare.com/workers/wrangler/) is
Cloudflare's official CLI for building, testing, and deploying Workers.
It's already listed as a devDependency, so `npm install` pulls it in — no
separate install needed. Used via `npx wrangler ...` or the `npm run dev`
script below. Relevant commands:

- `wrangler dev` — runs the server locally, simulating the Workers runtime
  (this is what `npm run dev` calls).
- `wrangler deploy` — publishes the code to Cloudflare's edge network under
  a real public URL.
- `wrangler secret put <NAME>` — securely uploads a secret (e.g. your eToro
  API key or the connector's bearer token) to the deployed Worker, without
  ever committing it to the repo.
- `wrangler.toml` — this repo's Workers config (build/name/routes).

Before `wrangler deploy` or `wrangler secret put` will work, log in once:

```bash
wrangler login
```

## Local development (`wrangler dev`)

1. Copy the example env file and fill in real values:

   ```bash
   cp .dev.vars.example .dev.vars
   ```

2. In `.dev.vars`, set:
   - `ETORO_API_KEY` / `ETORO_USER_KEY` — your eToro API credentials.
   - `CONNECTOR_AUTH_TOKEN` — a secret bearer token that guards this
     connector's own `/mcp` endpoint (unrelated to the eToro credentials
     above). Generate one with:

     ```bash
     openssl rand -hex 32
     ```

   `.dev.vars` is gitignored — never commit it.

3. Start the local Workers dev server:

   ```bash
   npm run dev
   ```

4. Every request to `/mcp` must include the bearer token:

   ```
   Authorization: Bearer <CONNECTOR_AUTH_TOKEN from .dev.vars>
   ```

   Requests missing the header, or presenting the wrong token, get a `401`.
   If `CONNECTOR_AUTH_TOKEN` isn't set at all, the server fails closed and
   rejects every request rather than allowing unauthenticated access.

## Running tests

```bash
npm test        # unit tests (node:test)
npm run typecheck
```

## Deploying and registering as a Claude connector

Deployment and connector registration are manual steps, done by the operator
(not run as part of this repo's automation):

1. **Set secrets on the deployed Worker** (never committed to the repo):

   ```bash
   wrangler secret put ETORO_API_KEY
   wrangler secret put ETORO_USER_KEY
   wrangler secret put CONNECTOR_AUTH_TOKEN
   ```

2. **Deploy:**

   ```bash
   wrangler deploy
   ```

   This publishes the Worker and prints its `*.workers.dev` URL (or a custom
   route, if configured).

3. **Register as a custom connector in Claude:**
   - In claude.ai, go to Settings → Connectors → Add custom connector.
   - Enter the deployed Worker's `/mcp` URL.
   - Complete the connector's auth step, supplying the same
     `CONNECTOR_AUTH_TOKEN` value set via `wrangler secret put` above.

4. **End-to-end check:** ask Claude a real portfolio question in a normal
   chat (e.g. "what's my eToro portfolio P&L right now?") and confirm it
   calls the right tool and returns live data.