Autonomous Traders using MCP

This project implements a multi-agent system of autonomous financial traders, each with a unique investment strategy inspired by a famous investor. The system is built using the Model Context Protocol (MCP) for microservice communication and features a real-time monitoring dashboard built with Gradio.

Features

• Multi-Agent System: Employs multiple autonomous agents (Trader and Researcher) that can collaborate.
• Distinct Trading Strategies: Each trader operates with a unique, pre-defined investment persona (e.g., Value Investing, Aggressive Macro).
• Real-time Dashboard: A Gradio-based web UI to monitor portfolio values, holdings, transactions, and agent activity logs in real-time.
• Microservice Architecture: Uses MCP to run different functionalities (account management, market data, web search) as independent, lightweight servers.
• Persistent State: Agent accounts, transactions, and logs are stored in a local SQLite database.
• Flexible Configuration: Easily configurable through a .env file to manage API keys, agent models, and execution settings.

System Architecture

The project is composed of three main parts: the Agents, the MCP Servers, and the Gradio UI.

1. Agents (traders.py, trading_floor.py):

   • The Trader Agent is the decision-maker. It analyzes market data, manages its portfolio, and executes trades based on its core strategy.
   • The Researcher Agent acts as a tool for the Trader. It can perform tasks like searching the web for news or fetching data, providing the Trader with up-to-date information.

2. MCP Servers (mcp_params.py, *_server.py):

   • These are small, independent microservices that provide tools to the agents.
   • accounts_server.py: Manages all portfolio data (balance, holdings, transactions).
   • market_server.py: Provides stock price information.
   • push_server.py: Sends push notifications.
   • Other servers for web search and memory are downloaded and run on-the-fly.

3. Gradio UI (app.py):

   • This is the visual frontend. It reads data directly from the database and presents it in a user-friendly dashboard, with cards for each trader that update automatically.

File Descriptions

File	Description
app.py	The Gradio web application. It creates the "Trading Floor" dashboard for monitoring all agents.
trading_floor.py	The main scheduler for running the agents. It initializes and runs the traders sequentially or on a timer.
traders.py	Defines the Trader class, which encapsulates the logic for creating and running a single agent, including its tools and MCP servers.
accounts.py	Contains the Account class, which handles the business logic for a portfolio (buying, selling, calculating P&L, etc.).
accounts_client.py	A client module for interacting with the accounts_server.py MCP server. It handles listing and calling tools, as well as reading account and strategy data.
database.py	Manages all interactions with the SQLite database (accounts.db), including reading and writing account data, market data, and logs.
market.py	Handles fetching stock market data, primarily from the Polygon.io API, with a fallback to random data.
mcp_params.py	Central configuration file that defines the commands and parameters for launching all the different MCP servers.
reset.py	A utility script to reset all trader accounts in the database to their default state.
tracers.py	Implements a custom tracing system that logs all agent actions (tool calls, thoughts) to the database for detailed monitoring.
*_server.py	Small scripts that define and run the MCP tool servers (e.g., accounts_server.py, market_server.py).

Setup and Installation

1. Prerequisites

• Python 3.10+
• Node.js and npm: Required to run some of the MCP servers. You can download it from nodejs.org.
• uv: This project uses uv for Python package management. If you don't have it, install it with:

  pip install uv

2. Clone the Repository

git clone <your-repository-url>
cd autonomous-traders

3. Create a Virtual Environment

Create and activate a virtual environment using uv.

uv venv
source .venv/bin/activate

4. Install Dependencies

Install all the required Python packages from requirements.txt.

uv pip install -r requirements.txt

5. Configure Environment Variables

Create a file named .env in the root of the project directory. This file will hold all your API keys and configuration settings.

# .env file

# --- Service API Keys ---

# Polygon.io API Key (for market data)
# Get one from [https://polygon.io/](https://polygon.io/)
POLYGON_API_KEY="YOUR_POLYGON_API_KEY"
# Set to "paid" or "realtime" if you have a subscription, otherwise leave it blank.
POLYGON_PLAN=""

# Brave Search API Key (for the Researcher agent's web search tool)
# Get one from [https://brave.com/api/](https://brave.com/api/)
BRAVE_API_KEY="YOUR_BRAVE_API_KEY"

# Pushover API Credentials (for push notifications)
# Get them from [https://pushover.net/](https://pushover.net/)
PUSHOVER_USER="YOUR_PUSHOVER_USER_KEY"
PUSHOVER_TOKEN="YOUR_PUSHOVER_API_TOKEN"


# --- Optional Model API Keys (if not using default models) ---

DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
GROK_API_KEY="YOUR_GROK_API_KEY"
OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
# The GOOGLE_API_KEY is often handled by SDKs, but can be set here if needed.
# GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"


# --- Execution Settings ---
# How often to run the agents, in minutes (if RUN_CONTINUOUSLY is true)
RUN_EVERY_N_MINUTES="60"
# Set to "true" to run agents even when the market is closed
RUN_EVEN_WHEN_MARKET_IS_CLOSED="false"
# Set to "true" to run the trading_floor script in a continuous loop
RUN_CONTINUOUSLY="false"
# Set to "true" to use a variety of LLMs for the agents (requires API keys above)
USE_MANY_MODELS="false"

Running the Application

There are three main ways to run the project:

1. Reset the Traders (Optional)

Before starting, you may want to reset all traders to their default state (balance of $10,000, no holdings).

uv run reset.py

2. Run the Trading Agents

This script runs the agents' decision-making processes. They will perform research, make trades, and update their accounts in the database.

To run all traders sequentially:

uv run trading_floor.py

To run only a single trader:

uv run trading_floor.py --trader Benjamin

(Replace Benjamin with the name of any trader: Jesse, Peter, or Tudor)

3. Launch the Dashboard

This command starts the Gradio web server, allowing you to monitor the agents in your browser.

uv run app.py

Open the URL provided in the terminal (usually http://127.0.0.1:7860) to view the Trading Floor dashboard.

Database Schema

The application uses a SQLite database file located at memory/accounts.db with the following tables:

Table Name	Schema (CREATE TABLE statement)
accounts	CREATE TABLE accounts (name TEXT PRIMARY KEY, account TEXT);
market	CREATE TABLE market (date TEXT PRIMARY KEY, data TEXT);
logs	CREATE TABLE logs (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, datetime DATETIME, type TEXT, message TEXT);