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

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

Product docs: TradeOS MCP integration & usage

---

Prerequisites

• Node.js 18+
• A TradeOS account with MCP API access
• For npm stdio: ability to run a local install (see 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):

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

claude --plugin-dir ./tradeos-skills

Then complete OAuth and run /tradeos:analyze. Full plugin workflow (validate, community marketplace submit): tradeos-skills/README.md — aligned with Claude plugin docs.

---

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:

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

# 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):

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:

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

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

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

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

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

Success:

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

   npm config set cache "%USERPROFILE%\.npm-cache"

1. npx @pkg tradeos-mcp-oauth may run the wrong bin on Windows. Prefer:

   npx -y -p @tradeos/tradeos-mcp tradeos-mcp-oauth

or node .../scripts/fetch-token.mjs from your install directory.

1. Clear a broken npx cache (quit Cursor first):

   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:

npm install @tradeos/tradeos-mcp

---

Development (this repo)

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:

git tag v1.0.0
git push origin v1.0.0

• Stable tags (v1.0.0) publish to npm latest and the MCP Registry.
• 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:

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/ — Claude Code plugin + analyze skill
• server.json — MCP Registry manifest
• TradeOS MCP FAQ (GitBook)