atsurae

1# atsurae
2 
3> AIが、あつらえる — AI-crafted video editing
4 
5MCP Server for AI-powered video editing. Let Claude, GPT, or any AI agent edit videos through natural language.
6 
7[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
9[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
10 
11---
12 
13## Quick Start
14 
15```bash
16# Install with pip
17pip install atsurae
18 
19# Or with uv
20uv pip install atsurae
21```
22 
23### Claude Desktop Configuration
24 
25Add to your Claude Desktop config (`claude_desktop_config.json`):
26 
27```json
28{
29  "mcpServers": {
30    "atsurae": {
31      "command": "python",
32      "args": ["-m", "atsurae"],
33      "env": {
34        "ATSURAE_API_URL": "https://api.atsurae.ai",
35        "ATSURAE_API_KEY": "your-api-key"
36      }
37    }
38  }
39}
40```
41 
42Then restart Claude Desktop. You can now edit videos through conversation.
43 
44---
45 
46## Features — 10 MCP Tools
47 
48| Tool | Description |
49|------|-------------|
50| `atsurae_inspect` | View project state at 3 detail levels: **L1** summary, **L2** structure, **L3** full timeline |
51| `atsurae_edit` | Add, move, trim, transform, and delete clips on the timeline |
52| `atsurae_audio` | Manage audio tracks — volume, ducking, BGM, narration |
53| `atsurae_semantic` | High-level operations: `close_all_gaps`, `snap_to_previous`, `reorder_clips` |
54| `atsurae_batch` | Execute up to 20 operations atomically in a single call |
55| `atsurae_preview` | Get visual preview frames, event points, and before/after diffs |
56| `atsurae_analyze` | Quality analysis — detect gaps, pacing issues, composition problems |
57| `atsurae_render` | Start, monitor, and download video renders |
58| `atsurae_history` | View operation history and rollback changes |
59| `atsurae_pipeline` | End-to-end AI video creation pipeline |
60 
61---
62 
63## Example
64 
65```
66You: Create a 30-second intro video with the uploaded avatar and background music
67 
68Claude: I'll create the intro video. Let me inspect the available assets first...
69 
70  [atsurae_inspect] → Found: avatar.mp4, bgm.mp3, logo.png
71  [atsurae_edit]    → Placed avatar on Layer 3, logo on Layer 5
72  [atsurae_audio]   → Added BGM with -6dB ducking under narration
73  [atsurae_semantic] → Closed all gaps, snapped clips
74  [atsurae_analyze] → Quality check passed (no gaps, good pacing)
75  [atsurae_render]  → Rendering at 1080p...
76 
77Claude: Your intro video is ready!
78        Duration: 30s | Resolution: 1920x1080 | Size: 12.4 MB
79        Download: https://api.atsurae.ai/renders/abc123/output.mp4
80```
81 
82---
83 
84## Architecture
85 
86```
87                    MCP Protocol                 REST API
88[You / AI Agent] ──────────────→ [atsurae MCP] ──────────→ [atsurae.ai API]
89                                   Server                        │
90                                                                 ▼
91                                                          [Video Engine]
92                                                                 │
93                                                                 ▼
94                                                          [FFmpeg Render]
95                                                                 │
96                                                                 ▼
97                                                           [Output MP4]
98```
99 
100**Layer Compositing Model:**
101 
102```
103L5: Telop / Text overlays
104L4: Effects (particles, transitions)
105L3: Avatar (chroma-keyed)
106L2: Screen capture / Slides
107L1: Background (3D space, gradients)
108```
109 
110Output: 1920x1080, 30fps, H.264 + AAC, MP4
111 
112---
113 
114## API
115 
116atsurae.ai also exposes a REST API that any AI agent can call directly, without MCP.
117 
118Documentation: [https://docs.atsurae.ai](https://docs.atsurae.ai) *(coming soon)*
119 
120---
121 
122## Development
123 
124```bash
125# Clone
126git clone https://github.com/1000ri-jp/atsurae.git
127cd atsurae
128 
129# Install with dev dependencies
130uv pip install -e ".[dev]"
131 
132# Run the MCP server locally
133python -m atsurae
134```
135 
136---
137 
138## Contributing
139 
140Contributions are welcome. Please open an issue first to discuss what you'd like to change.
141 
142---
143 
144## License
145 
146[MIT](LICENSE)
147 
148---
149 
150**atsurae** is built by [1000ri-jp](https://github.com/1000ri-jp).
151 
152*AIが、あつらえる* — AI crafts it for you.
153