Phrase MCP Server

Use Phrase APIs from any MCP client (Claude, Cursor, etc.) with ready-to-use tools for Phrase Strings, Phrase TMS, and Connectors.

Who This Is For

• Localization managers automating routine project and job operations
• Engineers building AI workflows around Phrase
• Teams that want one MCP server for both Strings and TMS
• Teams that want one MCP server for Strings, TMS, and Connectors workflows

Available Tools

Strings (strings_*)

strings_add_job_keys
strings_add_job_locale
strings_complete_job
strings_complete_job_locale
strings_compare_branch
strings_create_branch
strings_create_glossary
strings_create_glossary_term
strings_create_glossary_term_translation
strings_create_job
strings_create_job_comment
strings_create_job_template
strings_create_job_template_locale
strings_create_key
strings_create_locale
strings_create_locale_download
strings_create_project
strings_create_translation
strings_create_upload
strings_delete_branch
strings_delete_glossary_term
strings_delete_key
strings_delete_locale
strings_delete_project
strings_get_branch
strings_get_branch_comparison
strings_get_glossary
strings_get_glossary_term
strings_get_locale
strings_get_job
strings_get_job_comment
strings_get_job_locale
strings_get_job_template
strings_get_job_template_locale
strings_get_key
strings_get_locale_download
strings_get_project
strings_get_translation
strings_get_upload
strings_list_account_jobs
strings_list_branches
strings_list_formats
strings_list_glossaries
strings_list_glossary_terms
strings_list_job_comments
strings_list_job_locales
strings_list_job_template_locales
strings_list_job_templates
strings_list_jobs
strings_list_keys
strings_list_locales
strings_list_projects
strings_list_translations
strings_list_uploads
strings_lock_job
strings_merge_branch
strings_sync_branch
strings_remove_job_keys
strings_remove_job_locale
strings_reopen_job
strings_reopen_job_locale
strings_review_job_locale
strings_start_job
strings_unlock_job
strings_update_branch
strings_update_glossary
strings_update_glossary_term
strings_update_glossary_term_translation
strings_update_job
strings_update_job_locale
strings_update_key
strings_update_locale
strings_update_project
strings_update_translation

TMS (tms_*)

tms_create_job_from_file
tms_create_project
tms_create_project_from_template
tms_create_project_from_template_shorthand
tms_download_target_file_async
tms_evaluate_quality_profile
tms_download_target_file_by_async_request
tms_export_trans_memory
tms_get_async_limits
tms_get_async_request
tms_get_job
tms_get_project
tms_get_project_template
tms_get_termbase
tms_get_trans_memory
tms_import_trans_memory
tms_list_jobs
tms_list_pending_requests
tms_list_project_templates
tms_list_projects
tms_list_termbases
tms_list_trans_memories
tms_search_job_termbases
tms_search_jobs
tms_search_termbase_terms
tms_search_trans_memory
tms_set_job_status
tms_set_project_status
tms_update_job
tms_update_project
tms_upload_termbase

Quality Evaluator (bqe_*)

bqe_create_ai_check
bqe_create_quality_profile
bqe_delete_ai_check
bqe_delete_quality_profile
bqe_evaluate_segments
bqe_get_ai_check
bqe_get_analytics
bqe_get_quality_profile
bqe_list_ai_checks
bqe_list_quality_profiles
bqe_update_ai_check
bqe_update_quality_profile

Examples

The following examples build on each other as a complete end-to-end workflow: discover your projects, kick off a new translation with Phrase TMS, retrieve the result, and upload a localization file via Phrase Strings.

1. List all projects

User prompt: "List all my Phrase projects"

Expected behavior:

• Calls tms_list_projects and strings_list_projects in parallel
• Returns all projects from both Phrase TMS and Phrase Strings

Expected output:

Phrase TMS projects (3):
- My Marketing Campaign (ID: ...) — en → de, fr — Status: COMPLETED
- Product Documentation Q1 (ID: ...) — en → es — Status: NEW
- Mobile App Strings (ID: ...) — en → ja, zh — Status: IN_PROGRESS

Phrase Strings projects (2):
- Web App (ID: ...) — Account: Acme Corp
- Help Center (ID: ...) — Account: Acme Corp

2. Create a TMS project from a template and send a file for translation

User prompt: "Create a new TMS project from the tech documentation template and send the README for translation"

Expected behavior:

• Calls tms_list_project_templates to resolve the template by name
• Calls tms_create_project_from_template_shorthand to create the project
• Calls tms_create_job_from_file to upload the file and create a translation job

Expected output:

Created TMS project "README Translation" (ID: ...)
  Template: tech documentation
  Source: en → Target: es
  Status: NEW

Uploaded README.md as a translation job:
  Job UID: ...
  Target language: es
  Status: NEW

3. Check translation status and download the completed file

User prompt: "Check if the README translation job is done and download the translated file"

Expected behavior:

• Calls tms_get_job to check the current job status
• Calls tms_download_target_file_async to trigger async file generation
• Polls tms_get_async_request until the export is complete
• Calls tms_download_target_file_by_async_request to retrieve and save the file

Expected output:

Job "README.md"
  Project: README Translation
  Source: en → Target: es
  Status: DELIVERED
  Words: 535

Triggering async export... done
Downloading translated file... done

Saved to: README.es.md

4. Create a Strings project and upload a localization file

User prompt: "Create a new Strings project and upload docs/examples/en.json (Format: simple_json) for localization"

Expected behavior:

• Calls strings_create_project to create the project
• Calls strings_create_locale to add the source locale
• Calls strings_create_upload to upload the file and import translation keys
• Calls strings_get_upload to confirm the upload succeeded

Expected output:

Created Strings project "My App Config" (ID: ...)
  Account: Acme Corp

Added locale: English (en) — main locale

Uploading en.json (format: simple_json)... done
  Upload state: success
  Translation keys created: 14
  Translations created: 14

Connectors (connectors_*)

connectors_download_raw
connectors_list_connectors
connectors_list_content
connectors_upload_raw

Prerequisites

• Node.js 20+

Quick Start

Add to your MCP client

Use the published package with npx in your MCP client config.

Codex (~/.codex/config.toml)

[mcp_servers.phrase]
command = "npx"
args = ["-y", "@phrase/phrase-mcp-server"]

[mcp_servers.phrase.env]
PHRASE_STRINGS_TOKEN = "your_token" # Required for Strings tools, optional for TMS-only usage
PHRASE_TMS_TOKEN = "your_token" # Required for TMS tools, optional for Strings-only usage
PHRASE_CONNECTORS_TOKEN = "your_token" # Required for Connectors tools
PHRASE_ENABLED_PRODUCTS = "strings,tms,connectors" # Optional, defaults to all products
PHRASE_REGION = "eu"

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "phrase": {
      "command": "npx",
      "args": ["-y", "@phrase/phrase-mcp-server"],
      "env": {
        "PHRASE_STRINGS_TOKEN": "your_token",
        "PHRASE_TMS_TOKEN": "your_token",
        "PHRASE_CONNECTORS_TOKEN": "your_token",
        "PHRASE_ENABLED_PRODUCTS": "strings,tms,connectors",
        "PHRASE_REGION": "eu"
      }
    }
  }
}

Set at least one product token in your MCP client config:

• Minimum Strings setup:
  • PHRASE_STRINGS_TOKEN=your_token
  • PHRASE_REGION=eu
• Strings + TMS setup:
  • PHRASE_STRINGS_TOKEN=your_token
  • PHRASE_TMS_TOKEN=your_token
  • PHRASE_REGION=eu
• Connectors setup:
  • PHRASE_CONNECTORS_TOKEN=your_token
  • PHRASE_REGION=eu

Configuration Reference

Product selection

• PHRASE_ENABLED_PRODUCTS: comma-separated subset of strings,tms,bqe,connectors
• PHRASE_DISABLED_PRODUCTS: products removed from the enabled set
• Default behavior: all products enabled

Region selection

• Global:
  • PHRASE_REGION: eu or us (default eu)

Authentication

The server uses Phrase Platform API tokens. You need to create API tokens in your Phrase account and provide them as environment variables to the MCP server.

• Per product (STRINGS, TMS, etc.):
  • PHRASE_<PRODUCT>_TOKEN

Connectors notes

• Connectors v1 currently supports only google-drive.
• Connectors base URLs are built in and selected by PHRASE_REGION:
  • eu -> https://eu.phrase.com/connectors
  • us -> https://us.phrase.com/connectors
• Only stored Phrase connector credentials are supported in v1. Pass request.connectorUuid; inline googleDrive2Credentials are rejected.
• request.configuration is required and must be an object. Today it is forwarded as-is and is usually {}, but the wrapper still requires it because the upstream connector contract does.
• The request.path object is the main Google Drive contract. The wrapper only validates or normalizes a few cases and otherwise forwards the path unchanged.
• Google Drive list operations default to { "pathType": "ROOT" } when request.path is omitted.
• Google Drive requests default locale to en when the caller does not provide one.
• Google Drive uploads use the connector's direct stream-upload flow from file_path; Connectors file storage is not used in v1.
• XLIFF and async endpoints are intentionally out of scope in v1.

Path model summary:

• ROOT: connector navigation root. Use it for the first list call; it exposes entries such as My Drive and Shared drives.
• SHARED_DRIVES_ROOT: shared-drive picker. Use it to enumerate available shared drives.
• FOLDER: concrete folder listing target. Use it for list calls inside My Drive or a shared drive.
• FILE: concrete file target. Use it for downloads and as the final target shape for uploads.

Drive model summary:

• My Drive paths use "drive": { "driveType": "MY_DRIVE" }.
• Shared drive paths use "drive": { "driveType": "SHARED_DRIVE", "driveId": "..." }.
• parentChain describes the ancestry of the file or folder within the drive. For list calls at the top of a drive it is usually []. For file operations it points at the parent folders of the file.

MCP wrapper behavior:

• connectors_list_content:
  • defaults to ROOT when request.path is omitted
  • still requires request.configuration, which is usually {}
  • otherwise forwards the provided path unchanged
• connectors_download_raw:
  • requires an explicit FILE path
  • returns inline bytes plus optional saved_to instead of storing content in Connectors file storage
• connectors_upload_raw:
  • reads bytes from local file_path
  • rejects request.storageId because file storage uploads are out of scope in v1
  • fills request.name from the local filename when omitted
  • overwrites request.size with the actual file size
  • native Google Drive upload semantics expect a destination FILE path that includes the filename
  • accepts a FOLDER path as a convenience and rewrites it into a FILE path by appending the folder to parentChain and filling the filename from request.name or file_path
  • performs the upstream stream registration and PUT internally, even though MCP exposes it as one upload tool call

For a detailed Google Drive path and configuration guide, including Bruno-aligned examples and the exact MCP normalization rules, see docs/developer/connectors-google-drive.md.

Example root listing:

{
  "connector": "google-drive",
  "request": {
    "connectorUuid": "8d6655d6-1be2-46af-89c0-7615866d2523",
    "configuration": {}
  }
}

Example upload from a local file:

{
  "connector": "google-drive",
  "file_path": "./demo.txt",
  "request": {
    "connectorUuid": "8d6655d6-1be2-46af-89c0-7615866d2523",
    "configuration": {},
    "path": {
      "pathType": "FOLDER",
      "folderId": "root",
      "drive": { "driveType": "MY_DRIVE" },
      "parentChain": []
    }
  }
}

Security recommendations

• Use a dedicated service user token for automation
• Prefer least-privilege project manager permissions over admin-level roles

Privacy Policy

This server connects to Phrase APIs on your behalf using the credentials you provide. No data is collected or stored by this server itself. See the Phrase Privacy Policy for details on how Phrase handles your data.

Developer Documentation

For maintainer-facing docs, see:

• Developer docs index
• Running published vs local builds
• Releasing

Support

For support, please open an issue on GitHub or submit a request via Phrase Help Center.