diff --git a/README.md b/README.md
new file mode 100644
index 0000000..920404d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+# 🎵 Suno MCP Server
+
+MCP сервер для [Suno API](https://sunoapi.org) — генерация AI-музыки, текстов, видео, обработка аудио прямо из opencode.
+
+**24 инструмента**, rate limiter, proxy support, полное покрытие всех эндпоинтов.
+
+## 🚀 Быстрый старт
+
+```bash
+git clone https://git.hidosi.ru/Hidosi/suno-mcp-server.git
+cd suno-mcp-server/suno-server
+npm install
+```
+
+Сервер уже скомпилирован в `dist/` — можно запускать сразу.
+
+## ⚙️ Подключение к opencode
+
+Добавь в свой `opencode.json`:
+
+```json
+"mcp": {
+  "suno": {
+    "type": "local",
+    "command": ["node", "/путь/к/suno-server/dist/index.js"],
+    "env": {
+      "SUNO_API_KEY": "твой-api-ключ"
+    }
+  }
+}
+```
+
+Готовый конфиг лежит здесь: `.opencode/opencode.json`.
+
+Перезапусти opencode. Агентам будет доступен skill `suno` с инструкцией на русском.
+
+## 🔧 Переменные окружения
+
+| Переменная | Назначение |
+|---|---|
+| `SUNO_API_KEY` | API ключ (обязательно) |
+| `SUNO_HTTP_PROXY` | HTTP/S прокси (приоритет) |
+| `HTTPS_PROXY` | HTTP/S прокси |
+| `HTTP_PROXY` | HTTP прокси |
+
+## 🧪 Проверка
+
+```bash
+cd suno-server
+SUNO_API_KEY=твой-ключ node test-real.js
+```
+
+Сделает два безопасных вызова:
+1. `suno_get_credits` — проверит аутентификацию и покажет баланс
+2. `suno_boost_style` — 0.4 кредита, улучшит описание стиля
+
+С прокси:
+```bash
+SUNO_API_KEY=твой-ключ SUNO_HTTP_PROXY=http://proxy:8080 node test-real.js
+```
+
+## 🛠️ Инструменты (24 шт)
+
+| Инструмент | Эндпоинт | Кредиты |
+|---|:---|---:|
+| `suno_generate_music` | `POST /generate` | 12 |
+| `suno_generate_lyrics` | `POST /lyrics` | 0.4 |
+| `suno_generate_sounds` | `POST /generate/sounds` | 2.5 |
+| `suno_extend_music` | `POST /generate/extend` | 12 |
+| `suno_replace_section` | `POST /generate/replace-section` | 5 |
+| `suno_add_vocals` | `POST /generate/add-vocals` | 12 |
+| `suno_add_instrumental` | `POST /generate/add-instrumental` | 12 |
+| `suno_upload_and_cover` | `POST /generate/upload-cover` | 12 |
+| `suno_upload_and_extend` | `POST /generate/upload-extend` | 12 |
+| `suno_generate_mashup` | `POST /generate/mashup` | 12 |
+| `suno_separate_vocals` | `POST /vocal-removal/generate` | 10 |
+| `suno_separate_stems` | `POST /vocal-removal/generate` (split_stem) | 20 |
+| `suno_create_video` | `POST /generate/video` | 2 |
+| `suno_create_cover` | `POST /generate/cover` | 0 |
+| `suno_convert_to_wav` | `POST /generate/wav` | 0.4 |
+| `suno_boost_style` | `POST /style/generate` | 0.4 |
+| `suno_generate_persona` | `POST /generate/persona` | 0 |
+| `suno_get_task_status` | `GET /generate/record-info` | 0 |
+| `suno_get_timestamped_lyrics` | `GET /generate/timestamped-lyrics` | 0.5 |
+| `suno_get_lyrics_details` | `GET /generate/lyrics-info` | 0 |
+| `suno_get_wav_details` | `GET /generate/wav-info` | 0 |
+| `suno_get_vocal_separation_details` | `GET /vocal-removal/record-info` | 0 |
+| `suno_get_video_details` | `GET /generate/video-info` | 0 |
+| `suno_get_credits` | `GET /generate/credit` | 0 |
+
+## 📊 Модели
+
+| Модель | Длина | Особенности |
+|---|---|---|
+| `V4` | до 4 мин | Лучшее качество звука |
+| `V4_5` | до 8 мин | Умные промпты, быстрее |
+| `V4_5PLUS` | до 8 мин | Более насыщенный звук |
+| `V4_5ALL` | до 8 мин | Лучшая структура песни |
+| `V5` | до 8 мин | Музыкальность + скорость |
+| `V5_5` | до 8 мин | Кастомные голоса |
+
+## 📋 Лимиты
+
+- **Rate limit**: 20 запросов / 10 секунд
+- **Кредиты**: не истекают
+- **Стоимость**: $0.005 USD / кредит
+- **Файлы**: хранятся 15 дней после генерации
+
+## 📁 Структура проекта
+
+```
+suno-mcp-server/
+├── suno-server/
+│   ├── src/
+│   │   ├── index.ts       # Точка входа — MCP Server (stdio)
+│   │   ├── client.ts      # HTTP клиент + rate limiter + прокси
+│   │   ├── schemas.ts     # Zod схемы валидации параметров
+│   │   ├── tools.ts       # 24 MCP tool definitions → JSON Schema
+│   │   └── handlers.ts    # Обработчики + polling async-задач
+│   ├── dist/              # Скомпилированный JS
+│   ├── test-real.js       # Тестовый скрипт с реальным API
+│   ├── package.json
+│   └── tsconfig.json
+├── .opencode/
+│   ├── opencode.json              # Пример конфига
+│   └── skills/suno/SKILL.md       # Skill для агентов (русский)
+└── README.md
+```
+
+## 👩‍💻 Разработка
+
+```bash
+cd suno-server
+npm install
+npm run build    # однократная сборка
+npm run dev      # watch-режим
+```
+
+## 🔗 Ссылки
+
+- [Suno API документация](https://docs.sunoapi.org)
+- [Suno API сайт](https://sunoapi.org)
+- [MCP спецификация](https://modelcontextprotocol.io)
+- [opencode](https://opencode.ai)