TradeOS AI

tradeos-mcp

O TradeOS MCP permite conectar a inteligência de negociação da TradeOS a ferramentas de IA compatíveis com MCP, para que seu assistente possa analisar mercados, pesquisar tickers, comparar spreads, usar contexto macro e gerenciar agentes de negociação personalizados diretamente por meio de prompts em linguagem natural.

Visão geral

Este repositório publica @tradeos/tradeos-mcp no npm: uma ponte stdio MCP que faz proxy de ferramentas para o TradeOS Streamable HTTP (mcp-call). Você pode conectar de duas formas:

Modo	Melhor para	Autenticação
HTTP (recomendado)	Cursor, Claude Code, a maioria dos clientes MCP	OAuth no navegador do cliente
npm stdio	Clientes que suportam apenas command / stdio	Variável de ambiente TRADEOS_ACCESS_TOKEN

Endpoint de produção (ambos os modos eventualmente chamam este):

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

Documentação do produto: Integração e uso do TradeOS MCP

---

Pré-requisitos

• Node.js 18+
• Uma conta TradeOS com acesso à API MCP
• Para npm stdio: capacidade de executar uma instalação local (veja notas para Windows)

---

Opção A — HTTP (recomendado)

Sem instalação npm. O cliente lida com o OAuth.

Cursor

Edite a configuração do usuário ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):

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

Salve, reinicie o Cursor (ou atualize o MCP em Configurações → MCP) e conclua o OAuth quando solicitado.

Claude Code (plugin — recomendado)

Use o plugin incluído em tradeos-skills/:

claude --plugin-dir ./tradeos-skills

Em seguida, conclua o OAuth e execute /tradeos:analyze. Fluxo completo do plugin (validação, envio ao marketplace da comunidade): tradeos-skills/README.md — alinhado com a documentação de plugins do Claude.

---

Opção B — ponte npm stdio

Use quando seu cliente exigir um processo local (command + stdio).

1. Instale localmente

Não dependa de npx dentro do MCP no Windows (problemas de cache/caminho). Instale uma vez em um diretório fixo:

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

Fixe uma versão se preferir, por exemplo, @tradeos/tradeos-mcp@1.0.0.

2. Obtenha TRADEOS_ACCESS_TOKEN

Execute o auxiliar de OAuth (abre o navegador → faça login na TradeOS → imprime o 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 (recomendado):

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

Copie o JWT impresso (eyJ...). Para desenvolvimento local deste repositório, copie para .env:

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

Usuários finais que apenas npm install o pacote não precisam de .env — defina o token na configuração do cliente MCP (mcp.json).

Não envie tokens para o git.

3. Configure o 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..."
      }
    }
  }
}

Substitua YOU e o caminho pelo local real da sua instalação. Use barras normais ou barras invertidas escapadas no JSON.

Se o Cursor não encontrar node, defina o caminho completo:

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

Habilite tradeos-npm em Configurações → MCP. O status deve mostrar conectado com as ferramentas listadas.

4. Verifique no terminal (opcional)

Variáveis de ambiente em mcp.json não se aplicam ao seu shell. Defina o token na mesma sessão do terminal:

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

Sucesso:

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

Pressione Ctrl+C para parar. O Cursor inicia seu próprio processo; você não precisa manter este terminal aberto.

---

Notas para Windows

1. Use node local + caminho de instalação em mcp.json, não npx, para MCP.
2. Se erros de cache npm mencionarem C:\Program Files\nodejs\node_cache, execute uma vez:

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

3. npx @pkg tradeos-mcp-oauth pode executar o binário errado no Windows. Prefira:

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

   ou node .../scripts/fetch-token.mjs do seu diretório de instalação.
4. Limpe um cache npx quebrado (feche o Cursor primeiro):

   rmdir /s /q "%USERPROFILE%\.npm-cache\_npx"
   

---

Referência do pacote npm

Item	Valor
Pacote	@tradeos/tradeos-mcp
Nome no registro MCP	io.github.TradeOS-AI/tradeos-mcp
Bin: ponte MCP	tradeos-mcp
Bin: token OAuth	tradeos-mcp-oauth
Subcomando OAuth	oauth no bin tradeos-mcp

Instalação:

npm install @tradeos/tradeos-mcp

---

Desenvolvimento (este repositório)

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	Propósito
npm run build	Compilar a ponte stdio para build/
npm run oauth:token	OAuth no navegador → imprimir token
npm run registry:verify	Verificações pré-publicação (package.json ↔ server.json)
npm run registry:sync-version <ver>	Sincronizar versão a partir da tag de release

---

Publicação (mantenedores)

Envie uma tag de versão para acionar .github/workflows/publish-mcp.yml:

git tag v1.0.0
git push origin v1.0.0

• Tags estáveis (v1.0.0) publicam no npm latest e no Registro MCP.
• Tags de pré-lançamento (v1.0.0-beta.1) publicam com uma dist-tag npm correspondente ao rótulo de pré-lançamento (por exemplo, beta).
• Requer o segredo NPM_TOKEN do GitHub Actions (token Automation clássico para @tradeos).

Verifique na API do registro:

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

---

Solução de problemas

Sintoma	Causa provável	Correção
TRADEOS_ACCESS_TOKEN is required	Token não definido no env / mcp.json	Execute o auxiliar de oauth; defina env na configuração do MCP
unauthorized ao conectar	Token expirado ou inválido	Execute o oauth novamente; cole um JWT novo (sem o prefixo Bearer)
EPERM / node_cache	Cache npm em Program Files	npm config set cache "%USERPROFILE%\.npm-cache"
TAR_ENTRY_ERROR / 'tradeos-mcp' is not recognized	npx falhou no Windows	Instalação local + caminho node em mcp.json
MODULE_NOT_FOUND para node_modules/...	Script executado do diretório errado	cd para o diretório de instalação ou use caminho absoluto
Token funciona no terminal, mas não no Cursor	mcp.json de caminho ou token incompatível	Corresponda os caminhos; reinicie o Cursor / atualize o MCP
MCP conecta, mas sem ferramentas	Servidor errado habilitado	Desative entradas localhost quebradas; use a URL HTTP de produção ou um tradeos-npm funcional

---

Relacionados

• tradeos-skills/ — plugin Claude Code + habilidade de análise
• server.json — manifesto do Registro MCP
• FAQ do TradeOS MCP (GitBook)