# mcp-transkriptor

Local [MCP](https://modelcontextprotocol.io) server wrapping the
[Transkriptor developer API](https://developer.transkriptor.com). Transcribe audio,
video, public URLs (YouTube / Google Drive / Dropbox / OneDrive), and live meetings
(Google Meet / Microsoft Teams / Zoom); fetch transcription content and AI summaries;
export TXT / SRT / PDF / DOCX; manage files, folders, custom vocabulary and webhooks;
text-to-speech; and AI-chat knowledgebases. stdio transport.

## Requirements

- [uv](https://docs.astral.sh/uv/)
- A Transkriptor API key — see https://developer.transkriptor.com (authentication)

## Setup

```bash
git clone https://github.com/mickaelxd/mcp-transkriptor.git
cd mcp-transkriptor
cp .env.example .env      # then paste your TRANSKRIPTOR_API_KEY
uv sync
```

## Run / test

```bash
uv run mcp-transkriptor      # starts the stdio server (Ctrl-C to stop)
```

## Register in Claude Code

```bash
claude mcp add transkriptor -s user -- \
  uv run --directory /absolute/path/to/mcp-transkriptor mcp-transkriptor
```

Use the absolute path to your clone. Other MCP clients: point them at the same
`uv run --directory <path> mcp-transkriptor` command over stdio.

## Configuration

| Env var | Required | Purpose |
|---|---|---|
| `TRANSKRIPTOR_API_KEY` | yes | Sent as `Authorization: Bearer <key>`. |
| `TRANSKRIPTOR_ALLOWED_DIR` | no | Sandbox for `transcribe_local_file`; files outside are rejected. Defaults to the process working directory. |

## Tools

- **Transcribe:** `transcribe_local_file`, `transcribe_url`, `transcribe_meeting`
- **Read:** `get_file_content`, `get_file_detail`, `get_meeting_detail`, `get_summary`, `list_files`, `list_folders`, `get_user_details`
- **Export / edit:** `export_transcription`, `rename_file`, `delete_file`
- **Vocabulary:** `set_custom_vocabulary`, `get_custom_vocabulary`, `delete_custom_vocabulary`
- **Webhooks:** `create_webhook`, `list_webhooks`, `delete_webhook`
- **Text-to-speech:** `text_to_speech`
- **AI chat:** `list_knowledgebases`, `create_knowledgebase`, `add_file_to_knowledgebase`, `create_chat_session`, `chat_with_knowledgebase`

Base URL `https://api.tor.app/developer`, rate limit 1000 req/min. Everything keys
off the `order_id` returned by a transcribe call.

## Security

- **Your API key grants full account access.** `.env` is gitignored — keep it that
  way. Treat the key like a password and rotate it if it leaks.
- This server exposes **destructive** tools (`delete_file`, `delete_webhook`, and
  `set_custom_vocabulary`, which *replaces* existing vocabulary). If you run your MCP
  client without a tool-confirmation gate, an autonomous agent — or **indirect prompt
  injection via transcription content the model reads** — could trigger them. Prefer
  a client that confirms tool calls.
- `transcribe_local_file` uploads file contents to a third party (tor.app). Keep
  `TRANSKRIPTOR_ALLOWED_DIR` narrow; never point it at a directory holding secrets.
- `get_user_details` echoes account fields returned by the API; avoid pasting its raw
  output into shared logs.
- Webhooks require a public HTTP endpoint to *receive* events. This server can
  create / list / delete them, but does not host a receiver.

## License

MIT — see [LICENSE](LICENSE).