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"
   

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