Skip to main content
Glama
deenesjakoruzh
cactus001

TradingAgent

by cactus001
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

TradingAgent

Agente conversacional de trading en papel nativo de MCP con análisis de sentimiento FinBERT.

"Compra 10 AAPL si hoy baja de 200 $" — escríbelo, el agente se encarga del resto.

Tabla de contenidos

Related MCP server: Alpaca API MCP Server

Arquitectura

┌──────────────────────┐     ┌──────────────────────────────────────┐
│   CLI Agent (REPL)   │     │          Web UI (FastAPI)            │
│  claude-sonnet-4-6   │     │  Dark chat · WebSocket · marked.js   │
│  agentic loop        │     │  ngrok → shareable demo URL          │
└──────────┬───────────┘     └──────────────────┬───────────────────┘
           │  MCP (stdio)                        │  MCP (stdio, per session)
           └──────────────────┬──────────────────┘
                              │
           ┌──────────────────▼──────────────────┐
           │         FastMCP Server              │
           │     20 tools · 4 modules            │
           └────┬──────────┬──────────┬──────────┘
                │          │          │          │
          trading     market-data  sentiment  watchlist
           8 tools      5 tools    FinBERT    4 tools
                │          │          │          │
                └──────────┴──────────┴──────────┘
                                │
                  ┌─────────────▼──────────────┐
                  │   5-Layer Guardrail         │
                  │  input·llm·tool·exec·output │
                  └─────────────┬──────────────┘
                                │
                  ┌─────────────▼──────────────┐
                  │     Alpaca Paper API        │
                  │  real quotes · fake money   │
                  └─────────────┬──────────────┘
                                │
                  ┌─────────────▼──────────────┐
                  │      Alert Daemon           │
                  │  polls prices every 30s     │
                  │  fires conditional orders   │
                  └────────────────────────────┘

Inicio rápido

No se necesita cuenta de Alpaca en el modo mock.

1 — Instala

# Clone and enter project
git clone https://github.com/cactus001/TRADE-AGENT.git
cd TRADE-AGENT

# Install dependencies (Apple Silicon — use Homebrew Python)
uv sync --python /opt/homebrew/bin/python3.12

# Install dev dependencies for tests
uv sync --extra dev

2 — Configura

cp .env.example .env

Abre .env y rellena los valores:

ANTHROPIC_API_KEY=sk-ant-...          # required — get from console.anthropic.com
ALPACA_API_KEY=                        # optional — paper trading keys from alpaca.markets
ALPACA_SECRET_KEY=                     # optional — leave blank to use --mock mode

Nota: El modo mock funciona sin claves de Alpaca y ejecuta FinBERT sobre titulares reales de noticias falsas.

Ejecutar el agente

Opción A — REPL de CLI (chat de terminal)

# Mock mode (no Alpaca keys needed)
uv run python -m agent.cli_agent --mock

# Live paper trading (requires Alpaca keys in .env)
uv run python -m agent.cli_agent

Escribe comandos en lenguaje natural. Pulsa Ctrl+C para salir — la transcripción de la sesión se guarda automáticamente en transcripts/.

Opción B — Interfaz web (chat compartible)

# Mock mode
uv run python -m src.webapp --mock

# Live paper trading
uv run python -m src.webapp

Abre http://localhost:8000 en tu navegador: verás una interfaz de chat con tema oscuro que incluye:

  • Chips de llamadas a herramientas en directo que muestran qué herramientas MCP se están ejecutando

  • Indicador animado de «pensando» durante la inferencia

  • Tablas Markdown para los datos de cartera/órdenes

  • Marca de agua PAPER TRADING — NO REAL MONEY en todas las confirmaciones de órdenes

Opción C — Compartir vía ngrok (demo en vivo desde cualquier lugar)

Úsalo para entrevistas, demos o para compartir con cualquier persona a través de Internet.

Paso 1 — Instala ngrok

brew install ngrok

Paso 2 — Autentícate

  1. Ve a dashboard.ngrok.com/get-started/your-authtoken

  2. Copia tu authtoken personal

  3. Ejecuta:

ngrok config add-authtoken YOUR_REAL_TOKEN_HERE

Paso 3 — Inicia el servidor web

uv run python -m src.webapp --mock

Paso 4 — Abre el túnel (en una segunda terminal)

ngrok http 8000

ngrok imprimirá una URL pública como esta:

Forwarding  https://oboe-routing-difficult.ngrok-free.app → http://localhost:8000

Comparte esa URL — cualquier persona con el enlace puede abrir la interfaz de chat e interactuar con TradingAgent en tiempo real desde cualquier navegador, sin necesidad de que nada configure nada.

Opción D — Docker (Redis + interfaz web)

Docker Compose levanta dos servicios:

  • redis — redis:7-alpine, persiste en un volumen con nombre y se le hace un chequeo de estado antes de que arranque el agente

  • trading-agent — se compila desde Dockerfile, ejecuta la interfaz web en el puerto 8000 y se conecta a Redis automáticamente

# Copy env file and add your Anthropic key
cp .env.example .env
# edit .env — add ANTHROPIC_API_KEY (REDIS_URL is set automatically by compose)

# Build and start both services
docker-compose up --build

# Or run detached
docker-compose up --build -d

Abre http://localhost:8000 — la interfaz de chat esté en funcionamiento.

# Tail logs
docker-compose logs -f trading-agent

# Stop everything
docker-compose down

# Stop and wipe all volumes (resets state + Redis cache)
docker-compose down -v

Ejecuta el agente CLI en lugar de la interfaz web:

docker-compose run --rm trading-agent uv run python -m agent.cli_agent --mock

Ejemplo de conversación

You: what's my portfolio looking like

Agent: Portfolio — $101,432.20 total (+1.4% today)
  TSLA  15 shares  $248.20  +$190.50  (+5.4%)
  NVDA   5 shares  $134.50  -$43.00   (-6.0%)
  Cash  $94,890.50 available

You: what's the sentiment on NVDA right now

Agent: NVDA Sentiment (last 4h): BEARISH — score -0.41
  Top drivers:
  • "Analyst cuts NVDA target to $125"  (negative, -0.81)
  • "Nvidia faces rising competition"    (negative, -0.62)
  Recommendation: Consider waiting for stabilisation before adding.

You: buy 10 AAPL if it drops below $200 today

Agent: Day Limit Buy Preview  [PAPER TRADING — NO REAL MONEY]
  10 shares AAPL  ·  Limit @ $200.00
  AAPL currently: $212.95
  Expires: 4:00 PM ET today  ·  Max cost: $2,000.00
  Confirm? (yes/no)

You: yes

Agent: ✅ Order placed (ID: abc-12345)
  Limit buy active — AAPL will be purchased automatically if price hits $200.
  [PAPER TRADING — NO REAL MONEY]

You: alert me when TSLA drops below 240

Agent: ✅ Alert set — will notify when TSLA < $240.00
  Current price: $248.20  (monitoring every 30s)

Herramientas

20 herramientas divididas en 4 módulos:

Módulo

Herramientas

trading

get_account, get_positions, get_orders, place_order, cancel_order, cancel_all_orders, get_portfolio_history, get_asset_info

market-data

get_quote, get_bars, get_news, get_market_status, search_symbol

sentiment

get_sentiment, get_market_mood, explain_sentiment

watchlist

set_price_alert, get_active_alerts, cancel_alert, get_trade_history

Seguridad

Una canalización de protección de 5 capas se aplica sobre cada orden:

Capa

Qué detecta

Protección de entrada

Patrones de inyección de prompts en los mensajes del usuario

Protección de LLM

Instrucciones inyectadas ocultas en titulares de noticias; refuerza el prompt del sistema

Protección de herramientas

Formatos de ticker no válidos, cantidad negativa, precios requeridos ausentes, límites de cordura

Protección de ejecución

Una sola orden > 20 % de la cartera, pérdida diaria > 5 %, > 10 órdenes/hora, operaciones de lavado (< 5 min), disyuntor (SPY cae > 5 %)

Protección de salida

Rechazos del bróker, avisos de concentración posteriores a la operación

place_order impone un flujo obligatorio de dos pasos: confirm=False (vista previa) debe llamarse antes de confirm=True (ejecutar). Ninguna orden llega al bróker sin una confirmación explícita del usuario en la conversación.

FinBERT como servicio de producción

src/models/finbert.py convierte FinBERT (ProsusAI/finbert) de un script independiente a un servicio MCP invocable de nivel de producción:

Patrón

Implementación

Singleton

_instance a nivel de módulo, un modelo cargado por proceso

Carga diferida

El modelo no se carga hasta la primera llamada a analizar()

Candado de comprobación doble

threading.Lock con if self._loaded comprobado dentro del candado

Detección automática de dispositivo

CUDA → Apple MPS → CPU, sin necesidad de configurar el entorno

Inferencia por lotes

Agrupa listas de noticias en BATCH_SIZE=16 para evitar quedarse sin memoria OOM

Puntuación normalizada

Devuelve pos_prob − neg_prob en [-1.0, +1.0]

Caché con Redis

Clave sha256(headline), TTL de 1 hora — los titulares idénticos nunca tocan la GPU dos veces

Patrón de aciertos parciales

Consulta de caché por lote, solo los fallos van a FinBERT, los aciertos se devuelven en <1ms

Degradación elegante

Redis no disponible → la caché se convierte en un no-op y la inferencia se ejecuta con normalidad

En Apple Silicon, la inferencia se ejecuta en la GPU MPS (confirmado: device: mps). Con una caché de Redis caliente, las llamadas repetidas a get_sentiment sobre el mismo ciclo de noticias devuelven resultados al instante.

Estructura del proyecto

TRADE-AGENT/
├── agent/
│   └── cli_agent.py            # REPL — manual agentic loop, auto-saves transcripts
├── src/
│   ├── server.py                # FastMCP entry point — registers all 4 tool modules
│   ├── webapp.py                # FastAPI + WebSocket web interface
│   ├── config.py                # Pydantic settings — env vars with defaults
│   ├── state_manager.py         # Persistent state (~/.trading-agent/state.json)
│   ├── alert_daemon.py          # Background thread — polls prices every 30s
│   ├── models/
│   │   └── finbert.py           # FinBERT singleton service (production ML pattern)
│   ├── cache/
│   │   └── redis_cache.py       # Redis sentiment cache — partial-hit, 1h TTL, graceful degradation
│   ├── clients/
│   │   └── alpaca_client.py     # Thin wrapper around alpaca-py SDK
│   ├── guardrails/
│   │   ├── input_guard.py       # Regex injection pattern detection
│   │   ├── llm_guard.py         # News sanitisation + system prompt hardening
│   │   ├── tool_guard.py        # Symbol/qty/price validation
│   │   ├── execution_guard.py   # Size, loss, velocity, wash-trade, circuit-breaker
│   │   ├── output_guard.py      # Broker rejection + concentration check
│   │   └── guard_registry.py    # Wires all 5 layers into one object
│   ├── tools/
│   │   ├── trading.py           # 8 trading tools (place_order confirm gate)
│   │   ├── market_data.py       # 5 market data tools
│   │   ├── sentiment.py         # 3 FinBERT sentiment tools
│   │   └── watchlist.py         # 4 alert/history tools
│   └── static/
│       └── index.html           # Dark chat UI (WebSocket, marked.js, tool chips)
├── mock/
│   └── mock_provider.py         # MockAlpacaClient — full demo without API keys
├── tests/
│   ├── test_guardrails.py       # 15 tests across all 5 guardrail layers
│   └── test_sentiment.py        # 7 tests — singleton, batch, device detection
├── transcripts/                 # Auto-saved session logs (git-ignored)
├── pyproject.toml
├── docker-compose.yml
├── Dockerfile
└── .env.example

Pruebas

uv run pytest tests/ -v
# 22 passed

Variables de entorno

Variable

Obligatoria

Valor por defecto

Descripción

ANTHROPIC_API_KEY

Sí

—

Clave de API de Claude — console.anthropic.com

ALPACA_API_KEY

No

—

Clave de trading de papel de Alpaca — alpaca.markets

ALPACA_SECRET_KEY

No

—

Secreto de trading de papel de Alpaca

REDIS_URL

No

redis://localhost:6379

Cadena de conexión de Redis — se define automáticamente en docker-compose

MAX_ORDER_PCT

No

0.20

Máximo de una sola orden como fracción de la cartera

DAILY_LOSS_LIMIT

No

-0.05

Detener compras si el P&L del día cae por debajo de este valor

VELOCITY_LIMIT

No

10

Máximo de pedidos por hora

Persistencia

El agente guarda en un archivo las alertas, el historial de órdenes y los contadores de velocidad/operaciones de lavado:

~/.trading-agent/state.json

Este archivo vive fuera del directorio del proyecto y nunca se incluye en el repositorio. Bórralo para restablecer por completo el estado.

Stack tecnológico

Componente

Tecnología

SDK del agente

SDK de Python de Anthropic (claude-sonnet-4-6)

Protocolo de herramientas

MCP (Model Context Protocol) vía FastMCP

API del broker

Alpaca Paper Trading (alpaca-py)

Modelo de sentimiento

ProsusAI/FinBERT (Hugging Face)

Motor ML

PyTorch 2.x — MPS / CUDA / CPU automático

Caché de inferencia

Redis 7 — sha256-keyed, 1 h TTL, degradación elegante

Servidor web

FastAPI + Uvicorn + WebSocket

Frontend

Vanilla JS, marked.js, propiedades personalizadas de CSS

Contenedores

Docker + docker-compose (dos servicios: redis + trading-agent)

Túnel

ngrok (plan gratuito)

Gestor de paquetes

uv

Pruebas

pytest + pytest-asyncio

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
F
license - not found
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • Alpaca MCP Server

    jbkix06
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables large language models to interact with Alpaca's trading infrastructure using natural language, supporting stock/options trading, portfolio management, watchlist handling, and real-time market data access.
    MIT

  • Alpaca API MCP Server

    wlu03
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables trading and portfolio management through the Alpaca API, allowing users to place orders, manage positions and watchlists, access market data, and retrieve account information through natural language.
    54
    3
    ISC

  • Alpaca Trading MCP Server

    dogmaai
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables natural language trading operations through Alpaca's API, supporting stocks, options, crypto, portfolio management, and real-time market data with comprehensive order execution and account management capabilities.
    MIT

  • ReadyTrader-Stocks

    up2itnow0822
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to execute stock trading operations with built-in risk controls and human approval workflows. Supports paper trading simulation, real brokerage integration (Alpaca, Tradier), backtesting, sentiment analysis, and portfolio management while maintaining strict separation between AI intelligence and trade execution.
    MIT

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cactus001/TRADE-AGENT'

If you have feedback or need assistance with the MCP directory API, please join our Discord server