{
  "markdown": "# tradeos-mcp\n\nTradeOS 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.\n\n## Overview\n\nThis 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:\n\n| Mode                   | Best for                                    | Auth                           |\n| ---------------------- | ------------------------------------------- | ------------------------------ |\n| **HTTP** (recommended) | Cursor, Claude Code, most MCP clients       | Browser OAuth in the client    |\n| **npm stdio**          | Clients that only support `command` / stdio | `TRADEOS_ACCESS_TOKEN` env var |\n\nProduction endpoint (both modes ultimately call this):\n\n```text\nhttps://ai.tradeos.xyz/api/agent/mcp/mcp-call\n```\n\nProduct docs: [TradeOS MCP integration & usage](https://tradeos.gitbook.io/tradeosaifaq/tradeos-mcp-integration-and-usage)\n\n---\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/) **18+**\n- A TradeOS account with MCP API access\n- For npm stdio: ability to run a local install (see [Windows notes](#windows-notes))\n\n---\n\n## Option A — HTTP (recommended)\n\nNo npm install. The client handles OAuth.\n\n### Cursor\n\nEdit user config `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\\.cursor\\mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"tradeos\": {\n      \"url\": \"https://ai.tradeos.xyz/api/agent/mcp/mcp-call\"\n    }\n  }\n}\n```\n\nSave, restart Cursor (or refresh MCP in **Settings → MCP**), then complete OAuth when prompted.\n\n### Claude Code (plugin — recommended)\n\nUse the bundled plugin in [`tradeos-skills/`](tradeos-skills/):\n\n```bash\nclaude --plugin-dir ./tradeos-skills\n```\n\nThen 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).\n\n---\n\n## Option B — npm stdio bridge\n\nUse when your client requires a local process (`command` + stdio).\n\n### 1. Install locally\n\n**Do not rely on `npx` inside MCP on Windows** (cache/path issues). Install once to a fixed directory:\n\n```bash\nmkdir -p ~/tradeos-mcp-run   # Windows: mkdir %USERPROFILE%\\Downloads\\tradeos-mcp-run\ncd ~/tradeos-mcp-run         # Windows: cd %USERPROFILE%\\Downloads\\tradeos-mcp-run\nnpm install @tradeos/tradeos-mcp\n```\n\nPin a version if you prefer, e.g. `@tradeos/tradeos-mcp@1.0.0`.\n\n### 2. Get `TRADEOS_ACCESS_TOKEN`\n\nRun the OAuth helper (opens browser → log in on TradeOS → prints token):\n\n```bash\n# Linux / macOS\nnpx -y -p @tradeos/tradeos-mcp tradeos-mcp-oauth\n\n# Or subcommand on main bin:\nnpx -y @tradeos/tradeos-mcp oauth\n\n# Or, from your install directory:\nnode node_modules/@tradeos/tradeos-mcp/scripts/fetch-token.mjs\n```\n\n**Windows (recommended):**\n\n```cmd\ncd /d %USERPROFILE%\\Downloads\\tradeos-mcp-run\nnode node_modules\\@tradeos\\tradeos-mcp\\scripts\\fetch-token.mjs\n```\n\nCopy the printed JWT (`eyJ...`). For **local development of this repo**, copy into `.env`:\n\n```bash\ncp .example.env .env\n# TRADEOS_ACCESS_TOKEN=eyJ...\n```\n\nEnd users who only `npm install` the package do not need `.env` — set the token in MCP client config (`mcp.json`) instead.\n\n**Do not commit tokens to git.**\n\n### 3. Configure Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"tradeos-npm\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"C:/Users/YOU/Downloads/tradeos-mcp-run/node_modules/@tradeos/tradeos-mcp/build/index.js\"\n      ],\n      \"env\": {\n        \"TRADEOS_ACCESS_TOKEN\": \"eyJ...\"\n      }\n    }\n  }\n}\n```\n\nReplace `YOU` and the path with your actual install location. Use forward slashes or escaped backslashes in JSON.\n\nIf Cursor cannot find `node`, set the full path:\n\n```json\n\"command\": \"C:/nvm4w/nodejs/node.exe\"\n```\n\nEnable **tradeos-npm** in **Settings → MCP**. Status should show connected with tools listed.\n\n### 4. Verify in terminal (optional)\n\nEnvironment variables in `mcp.json` **do not** apply to your shell. Set the token in the **same** terminal session:\n\n```cmd\nREM Windows CMD\nset TRADEOS_ACCESS_TOKEN=eyJ...\nnode C:\\Users\\YOU\\Downloads\\tradeos-mcp-run\\node_modules\\@tradeos\\tradeos-mcp\\build\\index.js\n```\n\n```bash\n# Linux / macOS\nexport TRADEOS_ACCESS_TOKEN=eyJ...\nnode ~/tradeos-mcp-run/node_modules/@tradeos/tradeos-mcp/build/index.js\n```\n\nSuccess:\n\n```text\n[tradeos-mcp] remote: https://ai.tradeos.xyz/api/agent/mcp/mcp-call\n[tradeos-mcp] stdio bridge ready\n```\n\nPress `Ctrl+C` to stop. Cursor starts its own process; you do not need to keep this terminal open.\n\n---\n\n## Windows notes\n\n1. **Use local `node` + install path in `mcp.json`**, not `npx`, for MCP.\n2. If npm cache errors mention `C:\\Program Files\\nodejs\\node_cache`, run once:\n   ```cmd\n   npm config set cache \"%USERPROFILE%\\.npm-cache\"\n   ```\n3. **`npx @pkg tradeos-mcp-oauth`** may run the wrong bin on Windows. Prefer:\n   ```cmd\n   npx -y -p @tradeos/tradeos-mcp tradeos-mcp-oauth\n   ```\n   or `node .../scripts/fetch-token.mjs` from your install directory.\n4. Clear a broken npx cache (quit Cursor first):\n   ```cmd\n   rmdir /s /q \"%USERPROFILE%\\.npm-cache\\_npx\"\n   ```\n\n---\n\n## npm package reference\n\n| Item              | Value                                      |\n| ----------------- | ------------------------------------------ |\n| Package           | `@tradeos/tradeos-mcp`                     |\n| MCP Registry name | `io.github.TradeOS-AI/tradeos-mcp`         |\n| Bin: MCP bridge   | `tradeos-mcp`                              |\n| Bin: OAuth token  | `tradeos-mcp-oauth`                        |\n| OAuth subcommand  | `oauth` on bin `tradeos-mcp`               |\n\nInstall:\n\n```bash\nnpm install @tradeos/tradeos-mcp\n```\n\n---\n\n## Development (this repo)\n\n```bash\ngit clone https://github.com/TradeOS-AI/tradeos-mcp.git\ncd tradeos-mcp\nnpm ci\nnpm run build\nnpm run oauth:token    # browser OAuth → prints token (copy into .env if needed)\nnpm run registry:verify\n```\n\n| Script                                | Purpose                                             |\n| ------------------------------------- | --------------------------------------------------- |\n| `npm run build`                       | Compile stdio bridge to `build/`                    |\n| `npm run oauth:token`                 | Browser OAuth → print token                         |\n| `npm run registry:verify`             | Pre-publish checks (`package.json` ↔ `server.json`) |\n| `npm run registry:sync-version <ver>` | Sync version from release tag                       |\n\n---\n\n## Publishing (maintainers)\n\nPush a version tag to trigger [`.github/workflows/publish-mcp.yml`](.github/workflows/publish-mcp.yml):\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\n- Stable tags (`v1.0.0`) publish to npm **`latest`** and the [MCP Registry](https://registry.modelcontextprotocol.io/).\n- Pre-release tags (`v1.0.0-beta.1`) publish with an npm dist-tag matching the prerelease label (e.g. `beta`).\n- Requires GitHub Actions secret **`NPM_TOKEN`** (Classic **Automation** token for `@tradeos`).\n\nVerify on the registry API:\n\n```bash\ncurl \"https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.TradeOS-AI/tradeos-mcp\"\n```\n\n---\n\n## Troubleshooting\n\n| Symptom                                                 | Likely cause                      | Fix                                                                                  |\n| ------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------ |\n| `TRADEOS_ACCESS_TOKEN is required`                      | Token not set in env / `mcp.json` | Run oauth helper; set `env` in MCP config                                            |\n| `unauthorized` on connect                               | Expired or invalid token          | Re-run oauth; paste fresh JWT (no `Bearer` prefix)                                   |\n| `EPERM` / `node_cache`                                  | npm cache under `Program Files`   | `npm config set cache \"%USERPROFILE%\\.npm-cache\"`                                    |\n| `TAR_ENTRY_ERROR` / `'tradeos-mcp' is not recognized` | `npx` failed on Windows           | Local install + `node` path in `mcp.json`                                            |\n| `MODULE_NOT_FOUND` for `node_modules/...`               | Ran script from wrong directory   | `cd` to install dir or use absolute path                                             |\n| Token works in terminal, not in Cursor                  | `mcp.json` path or token mismatch | Match paths; restart Cursor / refresh MCP                                            |\n| MCP connects but no tools                               | Wrong server enabled              | Disable broken `localhost` entries; use production HTTP URL or working `tradeos-npm` |\n\n---\n\n## Related\n\n- [`tradeos-skills/`](tradeos-skills/) — Claude Code plugin + analyze skill\n- [`server.json`](server.json) — MCP Registry manifest\n- [TradeOS MCP FAQ (GitBook)](https://tradeos.gitbook.io/tradeosaifaq/tradeos-mcp-integration-and-usage)\n",
  "bytes": 9297,
  "sha": "6a7419b043d392e4788a3a68d92f9d9641f76e14d324094779d71a51b395812c",
  "repo_slug": "tradeos-ai/tradeos-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tradeos_ai_tradeos_mcp_test_7b757a38/readme"
}