turtle-mcp 0.1.0

MCP server exposing turtle graphics drawing tools for LLMs

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 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:

pip install turtle-mcp

Or with uv:

uv pip install turtle-mcp

Usage

With Claude Code

Add this to your Claude Code MCP settings (claude_desktop_config.json or .mcp.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

uvx turtle-mcp

Local Development

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