# Upservice MCP Server

*[Читать на русском](README.ru.md)*

An MCP (Model Context Protocol) server that wraps the [Upservice Public API](https://public.upservice.io/redoc) so Claude (or any MCP client) can manage employees, projects, sprints, tasks, tags, directories, and channel messages directly.

Built from the OpenAPI spec at `https://public.upservice.io/openapi.json`, verified against the live API.

## What it can do

60 tools covering:

- **Employees** — list employees
- **Projects** — list, create, get, update, delete, set managers/members, mark completed
- **Sprints** — list, create, get, update, delete, complete, activate, add tasks
- **Tags** — list, create, update, delete, assign/unassign to tasks/chats/assets/contacts/attachments, list the tags on one entity
- **Tasks** — list/search, create, get, update, delete, attachments, status changes, effort estimation, worklog (read entries / log effort), agreement (approval) workflow actions, co-responsibles, agreement/acquaintance sheets
- **Directories** (custom reference catalogs) — list/create/get/update/delete directories and their records, plus bulk relation management (linking records to tasks, projects, orders, etc.)
- **Channels & files** — load/send chat messages, send channel messages, upload files, get file download URLs

Every write tool exposes the well-documented fields explicitly (validated), and most also accept an `extra_fields` dict for advanced/uncommon fields documented in the Upservice API but not modeled individually.

**Mentioning employees:** Upservice only turns `@Name` into a real, notifying mention if it's written as `@[Name](employee_id)`. Tools that write text (`upservice_send_chat_message`, `upservice_send_channel_message`, `upservice_create_task`, `upservice_update_task`) accept a `mentions: [{employee_id, display_name}]` field — put a `{{employee_id}}` placeholder in your text and the server substitutes the correct syntax for you.

**Task filters:** `upservice_list_tasks` filters server-side by `status`, `sprint_id`, and `without_sprint` (`true` — only tasks with no sprint, `false` — only tasks with one). The API documents several `status`/`sprint_id` values as OR, but the live API applies only the last one, so the tool accepts a single value per call. `without_sprint=true` together with `sprint_id` is rejected by the tool before any request is sent.

## Setup

Get your Upservice API key first: in your Upservice account, go to account settings → API key. Keys look like `UPS-XXXX-XXXX-XXXX-XXXX`.

### Option A — `uvx` (recommended, no manual install)

Requires [`uv`](https://docs.astral.sh/uv/) installed (`brew install uv` or see their docs). `git` is **not** needed.

1. Download the project as a ZIP: open [the repository](https://github.com/alexherbaly/upservice-mcp) on GitHub and click **Code → Download ZIP**.
2. Unpack it wherever you like (e.g. `~/upservice-mcp`). The folder you point at below is the one that contains `pyproject.toml`.
3. Add to your MCP client config (e.g. `claude_desktop_config.json`), using the absolute path to that folder:

```json
{
  "mcpServers": {
    "upservice": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/upservice-mcp", "upservice-mcp"],
      "env": {
        "UPSERVICE_API_KEY": "UPS-XXXX-XXXX-XXXX-XXXX"
      }
    }
  }
}
```

`uv` builds and caches an isolated environment on first run; nothing is installed system-wide.

**Updating:** there is no auto-update. To get a newer version, download a fresh ZIP, replace the folder's contents, and restart your MCP client — `uv` rebuilds the environment from the changed source.

### Option B — plain venv + pip

```bash
cd upservice_mcp
python3 -m venv venv
venv/bin/pip install -r requirements.txt
```

```json
{
  "mcpServers": {
    "upservice": {
      "command": "/absolute/path/to/upservice_mcp/venv/bin/python3",
      "args": ["/absolute/path/to/upservice_mcp/src/upservice_mcp/server.py"],
      "env": {
        "UPSERVICE_API_KEY": "UPS-XXXX-XXXX-XXXX-XXXX"
      }
    }
  }
}
```

Restart Claude Desktop afterwards. The tools will appear prefixed with `upservice_`.

### Optional: custom base URL

If Upservice ever changes the API host, or you use a private/on-prem instance, override it:

```json
"env": {
  "UPSERVICE_API_KEY": "UPS-XXXX-XXXX-XXXX-XXXX",
  "UPSERVICE_API_BASE_URL": "https://public.upservice.io"
}
```

## Testing locally

```bash
# uvx
UPSERVICE_API_KEY=UPS-XXXX uvx --from . upservice-mcp

# venv
UPSERVICE_API_KEY=UPS-XXXX venv/bin/python3 src/upservice_mcp/server.py
```

Or test interactively with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector uvx --from . upservice-mcp
```

## Notes

- Authentication uses a raw API key in the `Authorization` header (not a `Bearer` token) — this server handles that for you.
- Destructive tools (`delete_*`, `unassign_tag`) are annotated with `destructiveHint: true` so MCP clients can warn users appropriately.
- Some request bodies documented by Upservice have many optional fields; where a tool doesn't model a field explicitly, pass it via `extra_fields` (a plain JSON object) and it will be merged into the request body.
- **Never share your own `UPSERVICE_API_KEY`** — each person should generate their own from their Upservice account settings.