# The Free Chart — Official MCP Server

[![smithery badge](https://smithery.ai/badge/@thefreechart/mcp)](https://smithery.ai/server/@thefreechart/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Official **Model Context Protocol (MCP)** Server for [The Free Chart](https://thefreechart.com) trading platform.

Connect any AI assistant (**Claude Desktop, Cursor, Windsurf, Zed, Antigravity, Open-WebUI, LibreChat**) to your trading journal to analyze winrate, monitor risk-to-reward, diagnose psychological biases (FOMO, Revenge Trading), and receive continuous AI trading coaching.

---

## ⚡ Quick Setup

### 1. Claude Desktop
Add to your `claude_desktop_config.json`:
* **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
* **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "thefreechart": {
      "command": "python3",
      "args": ["/path/to/thefreechart-mcp/server.py"],
      "env": {
        "THEFREECHART_API_KEY": "YOUR_PERSONAL_API_KEY",
        "THEFREECHART_BASE_URL": "https://manage.thefreechart.com"
      }
    }
  }
}
```

### 2. Cursor IDE / Windsurf
1. Open Cursor Settings -> **Features** -> **MCP Servers**.
2. Click **+ Add New MCP Server**:
   * **Name**: `The Free Chart`
   * **Type**: `command`
   * **Command**: `python3 /path/to/thefreechart-mcp/server.py`
   * **Env**: `THEFREECHART_API_KEY=your_key_here`

### 3. Smithery (1-Click Install)
```bash
npx -y @smithery/cli install @thefreechart/mcp --client claude
```

---

## 🛠️ Available Tools

| Tool | Type | Description |
| :--- | :--- | :--- |
| `get_journal_summary` | Read | Aggregated performance metrics (Winrate, Net PnL, Profit Factor, Max Drawdown, Avg R:R, Expectancy). |
| `get_trade_breakdown` | Read | Dynamic grouping by `day_of_week`, `hour_of_day`, `direction`, `symbol`, `setup_tag`, `mistake_tag`, `emotion_tag`, `duration_bracket`. |
| `search_trades_compact` | Read | High-speed columnar trade search (< 10 KB per 100 trades) with filtering. |
| `get_trade_detail` | Read | Single trade deep dive (executions, SL, TP, planned risk, notes, chart replay URL). |
| `get_daily_reflections` | Read | Retrieve trader's daily mood, pre-market plan, and end-of-day recaps. |
| `tag_trade_mistake_or_setup` | Write (Action) | AI automatically tags a trade with mistakes (`#FOMO`, `#EarlyExit`) or setups (`#LiquiditySweep`). |
| `save_ai_coaching_note` | Write (Action) | AI saves structured coaching advice directly into the user's trade note. |
| `create_daily_reflection` | Write (Action) | AI saves daily lessons and recap into the user's Daily Journal. |

---

## 💬 Example Prompt Starters

* **Daily Review**: *"Review my trades today, check if I broke any risk rules, tag mistakes and write a coaching review."*
* **Psychology Audit**: *"Analyze my trading for this week. Which day was most profitable, and which mistake cost me the most money?"*
* **Setup Evaluation**: *"Compare the winrate and average R:R of my setups over the past 30 days."*

---

## 📄 License
MIT License. © [The Free Chart](https://thefreechart.com).