# tradeos-mcp

TradeOS MCP lets you connect TradeOS trading intelligence to MCP-compatible AI tools, so your assistant can analyze markets, search tickers, compare spreads, use macro context, and manage custom trading agents directly from natural-language prompts.

## Overview

This repo publishes **`@tradeos/tradeos-mcp`** on npm: a **stdio MCP bridge** that proxies tools to TradeOS Streamable HTTP (`mcp-call`). You can connect in two ways:

| Mode                   | Best for                                    | Auth                           |
| ---------------------- | ------------------------------------------- | ------------------------------ |
| **HTTP** (recommended) | Cursor, Claude Code, most MCP clients       | Browser OAuth in the client    |
| **npm stdio**          | Clients that only support `command` / stdio | `TRADEOS_ACCESS_TOKEN` env var |

Production endpoint (both modes ultimately call this):

```text
https://ai.tradeos.xyz/api/agent/mcp/mcp-call
```

Product docs: [TradeOS MCP integration & usage](https://tradeos.gitbook.io/tradeosaifaq/tradeos-mcp-integration-and-usage)

---

## Prerequisites

- [Node.js](https://nodejs.org/) **18+**
- A TradeOS account with MCP API access
- For npm stdio: ability to run a local install (see [Windows notes](#windows-notes))

---

## Option A — HTTP (recommended)

No npm install. The client handles OAuth.

### Cursor

Edit user config `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\.cursor\mcp.json`):

```json
{
  "mcpServers": {
    "tradeos": {
      "url": "https://ai.tradeos.xyz/api/agent/mcp/mcp-call"
    }
  }
}
```

Save, restart Cursor (or refresh MCP in **Settings → MCP**), then complete OAuth when prompted.

### Claude Code (plugin — recommended)

Use the bundled plugin in [`tradeos-skills/`](tradeos-skills/):

```bash
claude --plugin-dir ./tradeos-skills
```

Then complete OAuth and run **`/tradeos:analyze`**. Full plugin workflow (validate, community marketplace submit): [`tradeos-skills/README.md`](tradeos-skills/README.md) — aligned with [Claude plugin docs](https://code.claude.com/docs/en/plugins#submit-your-plugin-to-the-community-marketplace).

---

## Option B — npm stdio bridge

Use when your client requires a local process (`command` + stdio).

### 1. Install locally

**Do not rely on `npx` inside MCP on Windows** (cache/path issues). Install once to a fixed directory:

```bash
mkdir -p ~/tradeos-mcp-run   # Windows: mkdir %USERPROFILE%\Downloads\tradeos-mcp-run
cd ~/tradeos-mcp-run         # Windows: cd %USERPROFILE%\Downloads\tradeos-mcp-run
npm install @tradeos/tradeos-mcp
```

Pin a version if you prefer, e.g. `@tradeos/tradeos-mcp@1.0.0`.

### 2. Get `TRADEOS_ACCESS_TOKEN`

Run the OAuth helper (opens browser → log in on TradeOS → prints token):

```bash
# Linux / macOS
npx -y -p @tradeos/tradeos-mcp tradeos-mcp-oauth

# Or subcommand on main bin:
npx -y @tradeos/tradeos-mcp oauth

# Or, from your install directory:
node node_modules/@tradeos/tradeos-mcp/scripts/fetch-token.mjs
```

**Windows (recommended):**

```cmd
cd /d %USERPROFILE%\Downloads\tradeos-mcp-run
node node_modules\@tradeos\tradeos-mcp\scripts\fetch-token.mjs
```

Copy the printed JWT (`eyJ...`). For **local development of this repo**, copy into `.env`:

```bash
cp .example.env .env
# TRADEOS_ACCESS_TOKEN=eyJ...
```

End users who only `npm install` the package do not need `.env` — set the token in MCP client config (`mcp.json`) instead.

**Do not commit tokens to git.**

### 3. Configure Cursor

```json
{
  "mcpServers": {
    "tradeos-npm": {
      "command": "node",
      "args": [
        "C:/Users/YOU/Downloads/tradeos-mcp-run/node_modules/@tradeos/tradeos-mcp/build/index.js"
      ],
      "env": {
        "TRADEOS_ACCESS_TOKEN": "eyJ..."
      }
    }
  }
}
```

Replace `YOU` and the path with your actual install location. Use forward slashes or escaped backslashes in JSON.

If Cursor cannot find `node`, set the full path:

```json
"command": "C:/nvm4w/nodejs/node.exe"
```

Enable **tradeos-npm** in **Settings → MCP**. Status should show connected with tools listed.

### 4. Verify in terminal (optional)

Environment variables in `mcp.json` **do not** apply to your shell. Set the token in the **same** terminal session:

```cmd
REM Windows CMD
set TRADEOS_ACCESS_TOKEN=eyJ...
node C:\Users\YOU\Downloads\tradeos-mcp-run\node_modules\@tradeos\tradeos-mcp\build\index.js
```

```bash
# Linux / macOS
export TRADEOS_ACCESS_TOKEN=eyJ...
node ~/tradeos-mcp-run/node_modules/@tradeos/tradeos-mcp/build/index.js
```

Success:

```text
[tradeos-mcp] remote: https://ai.tradeos.xyz/api/agent/mcp/mcp-call
[tradeos-mcp] stdio bridge ready
```

Press `Ctrl+C` to stop. Cursor starts its own process; you do not need to keep this terminal open.

---

## Windows notes

1. **Use local `node` + install path in `mcp.json`**, not `npx`, for MCP.
2. If npm cache errors mention `C:\Program Files\nodejs\node_cache`, run once:
   ```cmd
   npm config set cache "%USERPROFILE%\.npm-cache"
   ```
3. **`npx @pkg tradeos-mcp-oauth`** may run the wrong bin on Windows. Prefer:
   ```cmd
   npx -y -p @tradeos/tradeos-mcp tradeos-mcp-oauth
   ```
   or `node .../scripts/fetch-token.mjs` from your install directory.
4. Clear a broken npx cache (quit Cursor first):
   ```cmd
   rmdir /s /q "%USERPROFILE%\.npm-cache\_npx"
   ```

---

## npm package reference

| Item              | Value                                      |
| ----------------- | ------------------------------------------ |
| Package           | `@tradeos/tradeos-mcp`                     |
| MCP Registry name | `io.github.TradeOS-AI/tradeos-mcp`         |
| Bin: MCP bridge   | `tradeos-mcp`                              |
| Bin: OAuth token  | `tradeos-mcp-oauth`                        |
| OAuth subcommand  | `oauth` on bin `tradeos-mcp`               |

Install:

```bash
npm install @tradeos/tradeos-mcp
```

---

## Development (this repo)

```bash
git clone https://github.com/TradeOS-AI/tradeos-mcp.git
cd tradeos-mcp
npm ci
npm run build
npm run oauth:token    # browser OAuth → prints token (copy into .env if needed)
npm run registry:verify
```

| Script                                | Purpose                                             |
| ------------------------------------- | --------------------------------------------------- |
| `npm run build`                       | Compile stdio bridge to `build/`                    |
| `npm run oauth:token`                 | Browser OAuth → print token                         |
| `npm run registry:verify`             | Pre-publish checks (`package.json` ↔ `server.json`) |
| `npm run registry:sync-version <ver>` | Sync version from release tag                       |

---

## Publishing (maintainers)

Push a version tag to trigger [`.github/workflows/publish-mcp.yml`](.github/workflows/publish-mcp.yml):

```bash
git tag v1.0.0
git push origin v1.0.0
```

- Stable tags (`v1.0.0`) publish to npm **`latest`** and the [MCP Registry](https://registry.modelcontextprotocol.io/).
- Pre-release tags (`v1.0.0-beta.1`) publish with an npm dist-tag matching the prerelease label (e.g. `beta`).
- Requires GitHub Actions secret **`NPM_TOKEN`** (Classic **Automation** token for `@tradeos`).

Verify on the registry API:

```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.TradeOS-AI/tradeos-mcp"
```

---

## Troubleshooting

| Symptom                                                 | Likely cause                      | Fix                                                                                  |
| ------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------ |
| `TRADEOS_ACCESS_TOKEN is required`                      | Token not set in env / `mcp.json` | Run oauth helper; set `env` in MCP config                                            |
| `unauthorized` on connect                               | Expired or invalid token          | Re-run oauth; paste fresh JWT (no `Bearer` prefix)                                   |
| `EPERM` / `node_cache`                                  | npm cache under `Program Files`   | `npm config set cache "%USERPROFILE%\.npm-cache"`                                    |
| `TAR_ENTRY_ERROR` / `'tradeos-mcp' is not recognized` | `npx` failed on Windows           | Local install + `node` path in `mcp.json`                                            |
| `MODULE_NOT_FOUND` for `node_modules/...`               | Ran script from wrong directory   | `cd` to install dir or use absolute path                                             |
| Token works in terminal, not in Cursor                  | `mcp.json` path or token mismatch | Match paths; restart Cursor / refresh MCP                                            |
| MCP connects but no tools                               | Wrong server enabled              | Disable broken `localhost` entries; use production HTTP URL or working `tradeos-npm` |

---

## Related

- [`tradeos-skills/`](tradeos-skills/) — Claude Code plugin + analyze skill
- [`server.json`](server.json) — MCP Registry manifest
- [TradeOS MCP FAQ (GitBook)](https://tradeos.gitbook.io/tradeosaifaq/tradeos-mcp-integration-and-usage)