# Turtle MCP Server

An MCP (Model Context Protocol) server that lets LLMs draw beautiful turtle graphics in a live tkinter window. Ask Claude to draw stars, fractals, landscapes, flowers, and more — all rendered in real time.

## Features

- **14 drawing tools** across three categories: geometric, fractals, and nature
- **10 color palettes**: rainbow, sunset, ocean, forest, pastel, jewel, autumn, cherry, earth, neon
- **Live tkinter window** that persists between tool calls
- **Thread-safe architecture**: asyncio MCP server + tkinter on a daemon thread
- **Pydantic-validated parameters** with sensible defaults — every tool works out of the box

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) package manager
- A system with tkinter support (included with standard Python on Windows/macOS; install `python3-tk` on Linux)

## Installation

No manual install needed — `uvx` handles everything automatically.

To install explicitly:

```bash
pip install turtle-mcp
```

Or with uv:

```bash
uv pip install turtle-mcp
```

## Usage

### With Claude Code

Add this to your Claude Code MCP settings (`claude_desktop_config.json` or `.mcp.json`):

```json
{
  "mcpServers": {
    "turtle_mcp": {
      "command": "uvx",
      "args": ["turtle-mcp"]
    }
  }
}
```

Then ask Claude things like:
- "Draw a 7-pointed star with the sunset palette"
- "Draw a fractal tree in autumn with some wind"
- "Draw a Koch snowflake"
- "Draw a landscape at sunset with mountains and a lake"
- "Draw a bouquet of 7 flowers in a vase with the cherry palette"

### Standalone

```bash
uvx turtle-mcp
```

### Local Development

```bash
git clone https://github.com/your-username/turtle-mcp.git
cd turtle-mcp
uv sync
uv run turtle-mcp
```

## Tool Catalog

### Geometric (5 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `turtle_draw_star` | Multi-pointed star | `points`, `size`, `fill_color`, `palette` |
| `turtle_draw_spiral` | Archimedean, logarithmic, or Fibonacci spiral | `spiral_type`, `turns`, `palette` |
| `turtle_draw_mandala` | Concentric ring mandala with rotational symmetry | `layers`, `symmetry`, `style`, `palette` |
| `turtle_draw_rosette` | Overlapping-circles rosette | `petals`, `radius`, `filled`, `palette` |
| `turtle_draw_polygon_grid` | Tessellation of triangles, squares, or hexagons | `polygon`, `cell_size`, `rows`, `cols` |

### Fractals (4 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `turtle_draw_fractal_tree` | Recursive branching tree with seasonal colours | `depth`, `branch_angle`, `season`, `wind` |
| `turtle_draw_koch_snowflake` | Koch curve snowflake | `depth`, `size`, `fill_color` |
| `turtle_draw_sierpinski` | Sierpinski triangle | `depth`, `size`, `palette` |
| `turtle_draw_dragon_curve` | Heighway dragon curve | `iterations`, `segment_length`, `palette` |

### Nature (5 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `turtle_draw_flower` | Rose, sunflower, daisy, or tulip | `flower_type`, `petal_count`, `palette` |
| `turtle_draw_landscape` | Scenic landscape with sky, mountains, lake, trees | `time_of_day`, `mountains`, `lake`, `trees` |
| `turtle_draw_sun_moon` | Sun or moon scene with stars and rays | `celestial_body`, `num_stars`, `rays` |
| `turtle_draw_house` | Cottage, modern, or log cabin | `style`, `wall_color`, `garden` |
| `turtle_draw_bouquet` | Flower arrangement with optional vase | `flower_count`, `vase`, `palette` |

## Color Palettes

All tools that accept a `palette` parameter support these options:

| Palette | Colors |
|---------|--------|
| `rainbow` | Red, orange, yellow, green, blue, indigo, violet |
| `sunset` | Warm oranges, creams, deep blues |
| `ocean` | Deep navy to coral |
| `forest` | Dark to light greens |
| `pastel` | Soft pink, peach, yellow, mint, blue |
| `jewel` | Purple, mauve, gold, teal |
| `autumn` | Red, amber, burgundy, olive, orange |
| `cherry` | Pink to deep magenta |
| `earth` | Browns and tans |
| `neon` | Bright magenta, cyan, green, red, yellow |

## Architecture

```
turtle_mcp/
├── server.py              # FastMCP server + 14 tool registrations
├── utils.py               # Tk thread management, palettes, drawing helpers
└── drawings/
    ├── geometric.py       # Stars, spirals, mandalas, rosettes, tessellations
    ├── fractals.py        # Trees, Koch, Sierpinski, dragon curves
    └── nature.py          # Flowers, landscapes, celestial scenes, houses
```

**Threading model**: The MCP server runs an asyncio event loop on the main thread. A daemon thread hosts the tkinter/turtle event loop. Drawing calls are dispatched to the Tk thread via `root.after(0, callback)` and synchronized back with `threading.Event`.

## License

MIT
