Teamstorm Mcp Server

TeamStorm MCP Server

MCP-сервер для интеграции AI-агентов (Claude Code, Cursor) с TeamStorm API. Предоставляет 26 инструментов для работы с задачами, комментариями, атрибутами, вложениями, правами доступа, связями, пользователями, спринтами, workflow и списанием времени.

Быстрый старт

1. Запустите контейнер

docker compose up -d --build

Для полной чистой сборки (без кеша):

docker compose build --no-cache && docker compose up -d

Сервер будет доступен на http://localhost:3001/mcp, health-check — на http://localhost:3002/health.

> Доступ по сети (Linux-сервер): При запуске на Linux-сервере в локальной сети сервер автоматически доступен по IP-адресу сервера: http://192.168.x.x:3001/mcp. Используйте этот адрес вместо localhost при настройке Claude Code или Cursor на другой машине. Порт открывается на всех сетевых интерфейсах (0.0.0.0) автоматически — дополнительная настройка не требуется.

> Примечание: Переменная TEAMSTORM_API_TOKEN в .env не обязательна — в HTTP-режиме каждый клиент передаёт свой токен через заголовок Authorization. TEAMSTORM_API_URL можно передать через apiUrl в инструменте (автоматически дополняется до http:///cwm/public/api/v1), но обычно URL предконфигурирован на сервере и параметр не требуется.

2. Интеграция с Claude Code

Сервер уже запущен (см. шаг 1). Добавьте его в Claude Code:

claude mcp add --scope user --transport http teamstorm http://localhost:3001/mcp \
  -H "Authorization: PrivateToken ваш_токен"

> Примечание: PrivateToken — это ваш персональный токен TeamStorm. Он передаётся с каждым запросом и используется для аутентификации на стороне API.

3. Интеграция с Cursor

Создайте файл .cursor/mcp.json в корне проекта (или глобально в ~/.cursor/mcp.json):

{
  "mcpServers": {
    "teamstorm": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "PrivateToken ваш_токен"
      }
    }
  }
}

> Примечание: Замени ваш_токен на реальный PrivateToken TeamStorm. После добавления перезапустите Cursor — инструменты появятся в боковой панели MCP.

4. Проверка

После добавления перезапустите IDE и проверьте:

Покажи список пространств TeamStorm

Конфигурация

Переменные окружения

| Переменная | Описание | Обязательность | Пример | | --------------------- | -------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------ | | TEAMSTORM_API_URL | Базовый URL TeamStorm API | Нет (URL предконфигурирован на сервере; можно переопределить через apiUrl в инструменте) | http://teamstorm.local/cwm/public/api/v1 | | TEAMSTORM_API_TOKEN | PrivateToken для аутентификации | Нет (каждый клиент передаёт через Authorization заголовок) | your_token_here | | PORT | Порт для MCP сервера | Нет (по умолчанию 3001) | 3001 | | TRUST_PROXY | Доверять заголовку X-Forwarded-For (только за reverse-proxy) | Нет (по умолчанию false) | false |

> TEAMSTORM_API_URL задаётся глобально через .env. При необходимости можно переопределить через параметр apiUrl в отдельном инструменте — сервер автоматически дополняет URL до полного формата http:///cwm/public/api/v1.

Файл .env

cp .env.example .env

Использование

После интеграции с IDE вы можете использовать команды.

> Примечание: Параметр workspace обязателен во всех инструментах. Если установлена переменная окружения TEAMSTORM_WORKSPACE в .env, можно передавать workspace опционально — он подставится автоматически. Иначе указывайте его явно: "в пространстве TS".

Получить список задач:

Покажи список задач в пространстве TS

Получить задачу по ID:

Найди задачу TS-13 в пространстве TS

Создать задачу:

Создай задачу "Исправить баг" в пространстве TS
с типом "Дефект", исполнителем "ivan.ivanov" и папкой "разработка"

Работа с комментариями

Покажи комментарии к задаче TS-671 в пространстве TS
Добавь комментарий к задаче TS-671: "Готово к слиянию"

Работа с атрибутами

Покажи атрибуты задачи TS-671 в пространстве TS
Какие атрибуты есть в пространстве TS?

Работа с вложениями

Загрузить файл:

curl -X POST http://localhost:3001/upload \
  -H "Authorization: PrivateToken ваш_токен" \
  -F "file=@/path/to/file.pdf"

После загрузки получите uploadId. Прикрепите файл:

Прикрепи файл с ID abc-123 к задаче TS-100 в пространстве TS

Списания времени

Добавь списание 2ч 30м к задаче TS-671 в пространстве TS
Покажи списания времени по задаче TS-671

Работа с несколькими инстансами

Покажи задачи TS-100 в пространстве TS с URL http://teamstorm-staging.local/cwm/public/api/v1

> Примечание: При передаче apiUrl можно указать только домен (http://teamstorm-staging.local) — сервер автоматически добавит суффикс /cwm/public/api/v1.

Безопасность загрузки файлов

Endpoint POST /upload (Out-of-Band загрузка):

• Аутентификация — требуется PrivateToken или Bearer в Authorization
• Rate limiting — 10 запросов/мин на IP (с учётом TRUST_PROXY)
• Ограничение размера — макс. 50 МБ
• TTL — файлы удаляются через 1 час
• Права — только владелец (система) имеет доступ к файлу

Разработка

npm install
npm run dev       # hot reload
npm run build     # tsc → dist/
npm run test:run  # тесты
npm run lint      # ESLint

Архитектура

• src/index.ts — точка входа: HTTP-сервер (порт 3001) + health-check (3002) + OOB upload. Каждый MCP-запрос создаёт новый McpServer.
• src/client/teamstorm.ts — TeamStormClient: axios-клиент с setBaseUrl() для переключения URL в рантайме (автоматически дополняет неполные URL до /cwm/public/api/v1).
• src/tools/ — 26 инструментов по доменам. Каждый: Zod-схема с apiUrl + execute → клиент → Markdown.
• src/utils/ — Pino-логгер (с redact и ленивым NODE_ENV) + форматтеры (task, bytes, duration).

Структура проекта

teamstorm-mcp-server/
├── src/
│   ├── client/
│   │   ├── teamstorm.ts      # Единый axios-клиент: запросы к TeamStorm REST API,
│   │   │                      # rate-limit interceptors, санитизация заголовков в логах
│   │   └── types.ts          # Полные TS-интерфейсы всех сущностей TeamStorm
│   ├── tools/
│   │   ├── tasks/            # Инструменты для работы с задачами
│   │   │   ├── list.ts, get.ts, create.ts, update.ts, count.ts
│   │   │   ├── list-by-parent.ts, list-updated.ts
│   │   ├── comments/         # Инструменты для комментариев
│   │   │   ├── list.ts, create.ts, visibility.ts
│   │   ├── attributes/       # Инструменты для атрибутов
│   │   │   ├── get.ts, list.ts
│   │   ├── attachments/      # Инструменты для вложений
│   │   │   ├── list.ts, get.ts, versions-list.ts, version-get.ts, oob-upload.ts
│   │   ├── permissions/      # Инструменты для прав доступа
│   │   │   └── get.ts
│   │   ├── links/            # Инструменты для связей
│   │   │   └── get.ts
│   │   ├── users/            # Пользователи пространства
│   │   │   └── list.ts
│   │   ├── sprints/          # Спринты с фильтром по статусу
│   │   │   └── list.ts
│   │   ├── workflows/        # Доступные процессы
│   │   │   └── list.ts
│   │   ├── types/            # Типы задач
│   │   │   └── list.ts
│   │   ├── workspaces/       # Доступные пространства
│   │   │   └── list.ts
│   │   └── time-tracking/    # Списания времени
│   │       ├── create.ts, list.ts
│   ├── utils/
│   │   ├── formatters.ts     # Markdown-форматтеры: задачи, байты, длительность
│   │   └── logger.ts         # Pino-логгер: redact полей, ленивый NODE_ENV, pretty в dev
│   ├── config.ts             # Zod-валидация env, ленивый singleton (без process.exit на импорте)
│   └── index.ts              # Точка входа: HTTP (3001) + health-check (3002) + OOB upload
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md

Функциональность

Инструменты сгруппированы по доменам:

Задачи

| Инструмент | Описание | | -------------------------------- | ------------------------------------------------------------- | | teamstorm_list_tasks | Список задач с фильтрацией и пагинацией | | teamstorm_get_task | Полная информация о задаче по ID | | teamstorm_create_task | Создание задачи с указанием типа, исполнителя, папки, спринта | | teamstorm_update_task | Обновление параметров задачи | | teamstorm_get_task_count | Общее количество задач в пространстве | | teamstorm_list_tasks_by_parent | Задачи по родительскому элементу (папка или задача) | | teamstorm_list_updated_tasks | Задачи, изменённые за указанный период |

Комментарии

| Инструмент | Описание | | ---------------------------------- | ------------------------------------------------ | | teamstorm_list_task_comments | Все комментарии к задаче | | teamstorm_create_task_comment | Добавление комментария к задаче | | teamstorm_get_comment_visibility | Уровень доступа к комментарию (кто может видеть) |

Атрибуты

| Инструмент | Описание | | ------------------------------- | ---------------------------------------------- | | teamstorm_get_task_attributes | Значения атрибутов конкретной задачи | | teamstorm_list_attributes | Список пользовательских атрибутов пространства |

Вложения

| Инструмент | Описание | | ------------------------------------ | --------------------------------------------------------------- | | teamstorm_list_task_attachments | Список вложений задачи | | teamstorm_get_task_attachment | Метаданные конкретного вложения | | teamstorm_list_attachment_versions | Все версии вложений задачи | | teamstorm_get_attachment_version | Метаданные конкретной версии вложения | | teamstorm_attach_uploaded | Прикрепление загруженного файла к задаче (после POST /upload) |

Управление доступом

| Инструмент | Описание | | -------------------------------- | ------------------------ | | teamstorm_get_task_permissions | Правила доступа к задаче |

Связи

| Инструмент | Описание | | -------------------------- | ------------------------------- | | teamstorm_get_task_links | Связи задачи (связанные задачи) |

Справочники

| Инструмент | Описание | | --------------------------- | ------------------------------------------------------- | | teamstorm_list_users | Пользователи пространства (с поиском) | | teamstorm_list_sprints | Спринты с фильтром по статусу (active/completed/future) | | teamstorm_list_workflows | Доступные процессы (workflows) | | teamstorm_list_task_types | Типы задач | | teamstorm_list_workspaces | Доступные пространства (workspaces) |

Время

| Инструмент | Описание | | ----------------------------- | ------------------------------------------ | | teamstorm_create_time_entry | Добавление списания времени (трудозатраты) | | teamstorm_list_time_entries | История списаний времени по задаче |

---

Лицензия

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: madebyearth
• Source: madebyearth/teamstorm-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.