Content
Storm MCP Server
MCP server for integrating AI-agents (Claude Code, Cursor) with TeamStorm API. Provides **48 tools** for working with tasks, folders, documents, comments, attributes, attachments, access rights, links, users, sprints, workflow, and time logging.
## Quick Start
### 1. Run the Container
```bash
docker compose up -d --build
```
For a full cleanwithout cache):
```bash
build --no-cache && up -d
```
The be available at `http:3001/mcp`, and the health-check will be available at `http://localhost:3002/health`.
> **Network Access (Linux Server):** If `TEAMSTORM_API_TOKEN` is **not set**, the server listens on all interfaces (`0.0.0.0`) and is accessible by the server's IP address: `http://192.168.x.x:/mcp`. If `TEAMSTORM_API_TOKEN` is **set** (single-user deployment), the server automatically switches to `127.0.0.1` to protect the token. To restore network access with a set token, set `LISTEN_HOST=0.0.0.0` in `.env`.
> **Note:** The `TEAMSTORM_API_TOKEN` variable in `.env` is optional — in HTTP mode, each client sends through the `Authorization` header. `TEAMSTORM_API can be passed through `apiUrl` in the tool (automatically supplemented to `http://<host>/cwm/public/api/v1 usually, the URL is pre-configured on the server and the parameter required.
> 📦 **Deployment.** Deployment scenarios (local single/multi-user, remote server behind HTTPS, bare Node, multiple instances), update procedure, and diagnostics are covered in a separate guide — [README-deploy.md](README-deploy.md). Important: sessions are stored in memory, so clients need to reconnect after each rebuild.
### 2. Integration with Claude Code server is already running (see step 1). Add it Code:
```bash
claude mcp add --scope user --transport http teamstorm1/mcp \
-H "Authorization: PrivateToken your_token"
```
> **Note:** `PrivateToken` is your personal TeamStorm token. It is sent request and used for the API side.
### 3. Integration with Codex / Desktop
Add a section to `~/.codex/config There are two options depending on how the MCP server is running.
**Option A — token set on the server** (recommended for localIf `TEAMST_TOKEN` is already specified in `.env`, the server substitutes the token in requests to TeamStorm. Codex should not pass any headers:
```toml
[mcp_servers.teamstorm]
url = "http://localhost:3001/mcp"
```
**Option B — token passed by client** (multi-user deployment)
If the token is not set on the server, each client passes its token. Save it to an environment variable (in `~/.zshrc` or `~/.bashrc`):
```bash
export TEAMSTORM_TOKEN="your_token"
```
Then specify the name of this variable in the config:
```toml
[mcp_servers.teamstorm]
url =://localhost:3001/mcp"
bearer_token_env "TEAMSTORM_TOKEN"
```
> **Note:** Codex passes the token as `Authorization: Bearer <token>`, which is accepted by the server. Restart Codex after changing the config.
### 4. Integration with Cursor
Create a file `.cursor/mcp.json` in the project root (or globally in `~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"teamstorm": {
"url": "http://localhost:3001/mcp",
"headers": {
"Authorization": "PrivateToken your_token"
}
}
}
}
```
> **Note:** Replace `your_token` with PrivateToken TeamStorm., restart Cursor — the tools will appear in the MCP sidebar.
### 5. Integration with Claude Desktop
Custom Connectors (Settings → Connectors in the app) are **not suitable** — they connect to the server from the Anthropic cloud, not from the local machine, and do not see `http://localhost`. For a local HTTP server, you needio↔HTTP proxy [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), Desktop launches as a regular local MCP server.
Open the config through Claude → Settings… → Developer → Edit Config (or edit the file directly):
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"teamstorm": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"http://localhost:3001/mcp",
"--allow-http",
"--header",
"Authorization:${TEAMSTORM_AUTH_HEADER}"
],
"env": {
"TEAMSTORM_AUTH_HEADER": "PrivateToken your_token"
}
}
}
}
```
> **Note:** `--allow-http` is mandatory — `mcp-remote` requires HTTPS by default. The token is passed through `env` so that the space in the value `PrivateToken <token>` does not break the parsing of the `--header` argument. Node.js is required (for `npx`). After saving restart Claude Desktop (Quit, not just close the window the MCP tool icon will appear in the chat input field.
### 6. Verification
, restart the IDE and check:
```
Show list of Team
```
## Configuration
### Environment Variables
| Variable | Description | Mandatory | Example |
| --------------------- | -------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------ |
| `TEAMST_URL` | Base URL of TeamStorm API | No (URL is pre-configured on the server; can be overridden via `apiUrl` in the tool) | `http://teamstorm.local/cwm/public/api/v1` |
| `TEAMSTORM_API_TOKEN` | PrivateToken for authentication | No (each client passes through the `Authorization` header) | `your_token_here` |
| `TEAMSTORM_WORKSPACE` | Default workspace if the tool is called without `workspace` | No `MYSPACE` |
| `PORT` | Port for MCP server | No (default is 3001) | `3001` |
| `LISTEN_HOST` | Address the server listens to. If not set: `127.0.0.1` when `TEAMSTORM_API_TOKEN` is set, otherwise `0.0.0.0` | No | `0.0.0` |
| `TRUST_PROXY` | Trust the `X-Forwarded-For` header (only behind reverse-proxy) | No (default is `false`) | `false` |
> `TEAMSTORM_API_URL` is set globally through `.env`. If necessary, it can be overridden through the `apiUrl` parameter in a separate tool — the server automatically supplements the URL to the full format `http://<host>/cwm/v1`.
### .env File
```bash
cp .env.example .env
```
## Usage
After integration with the IDE, you can use commands.
> **Note:** The `workspace` parameter is mandatory in all tools. If the `TEAMSTORM_WORKSPACE` environment variable is set in `.env`, you can pass the workspace optionally — it will be substituted automatically. Otherwise, specify it explicitly: `"in TS space"`.
**Get taskShow list of tasks in TS space
```
**Get task by ID:**
```
Find task TS-13 in TS space
```
**Create task:**
```
Create task "Fix bug" in TS space
with type "Defect", performer "ivanov", and folder "development"
```
### Working with Folders
```
Show folder tree in TS space
Find folder "development" in TS space
Find all tasks in folder "Backend" duplicates analytics
```
### Working with Comments
```
Show comments to task TS-671 in
Add comment to task TS-671: "Ready for merge"
```
### Working with Attributes
```
Show attributes of task TS-671 in TS space
What attributes are there in TS space?
```
### Working with Attachments
**Upload file:**
```bash
curl -X POST http://localhost:3001/upload \
-H "Authorization: PrivateToken your_token" \
-F "file=@/path/to/file.pdf"
```
After uploading, get `uploadId`. Attach the file:
```
Attach file with ID abc-123 to task TS-100 in TS space
```
### Time Logging
```
Add time logging 2h 30m to task TS-671 in TS space
Show time logging-671
```
### Working with Multiple Instances
```
Show tasks TS-100 in TS space with URL http://teamstorm-staging.local/cwm/public/api/v1
```
> **Note:** When passing `apiUrl`, you can specify only the domain (`http://teamstorm-staging.local`) — the server will automatically add the suffix `/cwm/public/api/v1`.
## Security of File Uploading
Endpoint `POST /upload` (Out-of-Band upload):
- **Authentication** — `PrivateToken` or `Bearer` in `Authorization` is required
- **Rate limiting** — 10 requests/min per IP (considering `TRUST_PROXY`)
- **Size limitation** — max 50 MB
- **TTL** — files are deleted after 1 hour
- **Permissions** — only the owner (system) has access to the file
## Development
```bash
npm install
npm run dev # hot reload
npm run build # tsc → dist/
npm run test:run # tests
npm run lint # ESLint
```
## Architecture
- **`src/index.ts`** — entry point: HTTP server (port 3001) + health-check (3002) + OOB upload. Each MCP request creates a new `McpServer`.
- **`src/client/teamstorm.ts`** — `TeamStormClient`: axios client with `setBaseUrl()` for switching URL at runtime (automatically completes incomplete URLs to `/cwm/public/api/v1`).
- **`src/tools/`** — 48 tools by domains. Each: Zod schema with `apiUrl` + `execute` → client → Markdown.
- **`src/utils/`** — Pino logger (with redact and lazy NODE_ENV) + formatters (task, bytes, duration).
## Project Structure
```
teamstorm-mcp-server/
├── src/
│ ├── client/
│ │ ├── teamstorm.ts # Single axios client: requests to TeamStorm REST API,
│ │ │ # rate-limit interceptors, sanitization of headers in logs
│ │ └── types.ts # Complete TS interfaces of all TeamStorm entities
│ ├── tools/
│ │ ├── folders/ # Tools for working with folders
│ │ │ ├── list.ts, get.ts, get-tree.ts, find.ts
│ │ ├── tasks/ # Tools for working with tasks
│ │ │ ├── list.ts, get.ts, create.ts, update.ts, count.ts
│ │ │ ├── list-by-parent.ts, list-updated.ts
│ │ ├── comments/ # Tools for comments
│ │ │ ├── list.ts, create.ts, visibility.ts
│ │ ├── attributes/ # Tools for attributes
│ │ │ ├── get.ts, list.ts
│ │ ├── attachments/ # Tools for attachments
│ │ │ ├── list.ts, get.ts, versions-list.ts, version-get.ts, oob-upload.ts
│ │ ├── permissions/ # Tools for access rights
│ │ │ └── get.ts
│ │ ├── links/ # Tools for links
│ │ │ └── get.ts
│ │ ├── documents/ # Tools for documents
│ │ │ ├── list.ts, get.ts, create.ts, update.ts, block.ts, unblock.ts
│ │ ├── document-sharing/ # Access to documents
│ │ │ ├── list.ts, create.ts, update.ts
│ │ ├── document-statuses/ # Document statuses
│ │ │ ├── list.ts, get.ts
│ │ ├── document-links/ # Document links with tasks
│ │ │ ├── list-tasks.ts, create.ts, list-documents.ts
│ │ ├── document-comments/ # Comments to documents
│ │ │ ├── list.ts, create.ts
│ │ ├── users/ # Space users
│ │ │ └── list.ts
│ │ ├── sprints/ # Sprints with status filter
│ │ │ └── list.ts
│ │ ├── workflows/ # Available processes
│ │ │ └── list.ts
│ │ ├── types/ # Task types
│ │ │ └── list.ts
│ │ ├── workspaces/ # Available spaces
│ │ │ └── list.ts
│ │ └── time-tracking/ # Time tracking
│ │ ├── create.ts, list.ts
│ ├── utils/
│ │ ├── formatters.ts # Markdown formatters: tasks, bytes, duration
│ │ └── logger.ts # Pino logger: redact fields, lazy NODE_ENV, pretty in dev
│ ├── config.ts # Zod validation of env, lazy singleton (without process.exit on import)
│ └── index.ts # Entry point: HTTP (3001) + health-check (3002) + OOB upload
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md
```
## Functionality
Tools are grouped by domains:
### Folders
| Tool | Description |
| --------------------------- | --------------------------------------------------------------------------- |
| `teamstorm_list_folders` | List of folders with filtering by name and parent folder |
| `teamstorm_get_folder` | Information about a folder by UUID |
| `teamstorm_get_folder_tree` | Full folder tree in one request (automatic pagination) |
| `teamstorm_find_folder` | Search for a folder by name (substring, any level) or ID with path to root |
| `teamstorm_create_folder` | Creating a folder (name, description, parent folder) |
| `teamstorm_update_folder` | Changing the name/description of a folder, moving to another folder |
### Tasks
| Tool | Description |
| --------------------------- | ------------------------------------------------------------- |
| `teamstorm_list_tasks` | List of tasks with filtering and pagination |
| `teamstorm_get_task` | Full information about a task by ID |
| `teamstorm_create_task` | Creating a task with type, performer, folder, sprint |
| `teamstorm_update_task` | Updating task parameters |
| `teamstorm_get_task_count` | Total number of tasks in the space |
| `teamstorm_list_tasks_by_parent` | Tasks by parent element (folder or task) |
| `teamstorm_list_updated_tasks` | Tasks changed during a specified period |
### Comments
| Tool | Description |
| ---------------------------- | ---------------------------------------------------- |
| `teamstorm_list_task_comments` | All comments to a task |
| `teamstorm_create_task_comment` | Adding a comment to a task |
| `teamstorm_get_comment_visibility` | Access level to a comment (who can see) |
### Attributes
| Tool | Description |
| ------------------------------- | -------------------------------------------------------------------- |
| `teamstorm_get_task_attributes` | Attribute values of a specific task |
| `teamstorm_list_attributes` | List of user attributes of the space |
| `teamstorm_create_attribute` | Creating an attribute (name, type, description, options for UniSelect/Tag) |
| `teamstorm_update_attribute` | Changing the name/description and set of options of an attribute |
| `teamstorm_add_attribute_option` | Adding an option to a UniSelect/Tag attribute |
| `teamstorm_update_attribute_option` | Renaming an attribute option by its UUID |
### Attachments
| Tool | Description |
| ------------------------------- | ------------------------------------------------------------------ |
| `teamstorm_list_task_attachments` | List of task attachments |
| `teamstorm_get_task_attachment` | Metadata of a specific attachment |
| `teamstorm_list_attachment_versions` | All versions of task attachments |
| `teamstorm_get_attachment_version` | Metadata of a specific version of an attachment |
| `teamstorm_attach_uploaded` | Attaching an uploaded file to a task (after `POST /upload`) |
### Access Management
| Tool | Description |
| --------------------------- | --------------------------- |
| `teamstorm_get_task_permissions` | Access rules to a task |
### Links
| Tool | Description |
| -------------------- | ----------------------------------- |
| `teamstorm_get_task_links` | Task links (related tasks) |
### Documents
| Tool | Description |
| ----------------------------- | --------------------------------------------------------------------------- |
| `teamstorm_list_documents` | List of space documents with pagination |
| `teamstorm_get_document` | Document by ID, including content |
| `teamstorm_create_document` | Create document (name, content, parent, labels) |
| `teamstorm_update_document` | Change document status (public API only supports the status field) |
| `teamstorm_block_document` | Block document from editing |
| `teamstorm_unblock_document` | Unblock document |
### Document Access
| Tool | Description |
| -------------------------------- | ------------------------------------------------------------------------ |
| `teamstorm_list_document_permissions` | List of document permissions (users and groups) |
| `teamstorm_share_document` | Grant access to user/group (Read, Edit, Comment) |
| `teamstorm_update_document_permission` | Change existing permission level |
### Document Statuses
| Tool | Description |
| ---------------------------- | -------------------------------------------- |
| `teamstorm_list_document_statuses` | List of available document statuses |
| `teamstorm_get_document_status` | Document status by ID |
### Document Links
| Tool | Description |
| ----------------------------- | ------------------------------------------------- |
| `teamstorm_get_document_task_links` | Tasks linked to document |
| `teamstorm_link_document_to_task` | Link document to task |
| `teamstorm_get_task_document_links` | Documents linked to task |
### Document Comments
| Tool | Description |
| ----------------------------- | -------------------------------------- |
| `teamstorm_list_document_comments` | All comments on document |
| `teamstorm_create_document_comment` | Add comment to document |
### References
| Tool | Description |
| --------------------- | ----------------------------------------------------------- |
| `teamstorm_list_users` | Space users (with search) |
| `teamstorm_list_sprints` | Sprints with status filter (active/completed/future) |
| `teamstorm_list_workflows` | Available workflows |
| `teamstorm_list_task_types` | Task types |
| `teamstorm_list_workspaces` | All available workspaces, all pages |
### Time
| Tool | Description |
| ----------------------- | --------------------------------------------- |
| `teamstorm_create_time_entry` | Add time entry (time spent) |
| `teamstorm_list_time_entries` | Time entry history for task |
---
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available