# Phrase MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with [Phrase Strings](https://phrase.com/), the translation management platform. This server enables AI assistants to interact with your Phrase projects, manage translation keys, and handle translations programmatically.

## Features

- **Project Management**: List, view, and create Phrase projects
- **Translation Keys**: Create, read, update, and delete translation keys
- **Translations**: Manage translations across multiple locales
- **Locale Management**: Configure and manage project locales
- **Search & Filter**: Query keys and translations with flexible filters

## Installation

### Prerequisites

- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- A Phrase account with API access

### Setup

1. Clone the repository:
```bash
git clone https://github.com/yourusername/phrase-mcp-server.git
cd phrase-mcp-server
```

2. Install dependencies using uv:
```bash
uv sync
```

3. Create a `.env` file with your Phrase API token:
```bash
cp .env.example .env
```

4. Edit `.env` and add your Phrase API token:
```
PHRASE_API_TOKEN=your_phrase_api_token_here
```

You can generate an API token in your Phrase account at: https://app.phrase.com/settings/oauth_access_tokens

## Usage

### Running the Server

The server uses stdio for communication with MCP clients:

```bash
uv run python -m phrase_mcp_server
```

### Configuring with Claude Desktop

Add this to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "phrase": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/phrase-mcp-server",
        "run",
        "python",
        "-m",
        "phrase_mcp_server"
      ],
      "env": {
        "PHRASE_API_TOKEN": "your_phrase_api_token_here"
      }
    }
  }
}
```

Replace `/ABSOLUTE/PATH/TO/phrase-mcp-server` with the actual path to your project directory.

### Available Tools

The server provides the following tools:

#### Projects
- `list_projects` - List all projects in your account
- `get_project` - Get details about a specific project
- `create_project` - Create a new project

#### Translation Keys
- `list_keys` - List translation keys in a project
- `get_key` - Get details about a specific key
- `create_key` - Create a new translation key
- `update_key` - Update an existing key
- `delete_key` - Delete a translation key

#### Translations
- `list_translations` - List translations (optionally filter by locale)
- `get_translation` - Get a specific translation
- `create_translation` - Create a new translation
- `update_translation` - Update an existing translation

#### Locales
- `list_locales` - List all locales in a project
- `get_locale` - Get details about a specific locale
- `create_locale` - Create a new locale

## Example Usage

Once configured, you can ask Claude to interact with your Phrase projects:

> "Show me all my Phrase projects"

> "Create a new translation key 'welcome_message' in project XYZ with description 'Welcome screen greeting'"

> "List all English translations in the mobile app project"

> "Update the German translation for key 'app.title' to 'Meine Anwendung'"

## Development

### Project Structure

```
phrase-mcp-server/
├── src/
│   └── phrase_mcp_server/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py      # Main MCP server implementation
│       └── client.py      # Phrase API client
├── pyproject.toml
├── .env.example
└── README.md
```

### Running Tests

```bash
uv run pytest
```

### Code Quality

The project uses modern Python practices:
- Type hints throughout
- Async/await for I/O operations
- Comprehensive error handling

## API Reference

This server uses the [Phrase Strings API v2](https://developers.phrase.com/api/). For detailed information about API endpoints and parameters, refer to the official Phrase API documentation.

## Legal & Open Source

This is an **unofficial** community project and is not affiliated with or endorsed by Phrase. The server:
- Uses Phrase's official public API
- Requires users to provide their own API credentials
- Does not redistribute any Phrase proprietary content
- Provides only an interface to access Phrase services

### License

MIT License - see LICENSE file for details.

### Disclaimer

This software is provided "as is", without warranty of any kind. Users are responsible for complying with Phrase's Terms of Service and API usage policies.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## Support

For issues related to:
- **This MCP server**: Open an issue on GitHub
- **Phrase API**: Contact [Phrase Support](https://support.phrase.com/)
- **MCP Protocol**: See [Model Context Protocol docs](https://modelcontextprotocol.io/)

## Changelog

### 0.1.0 (2026-01-14)
- Initial release
- Support for projects, keys, translations, and locales
- Full CRUD operations for all resource types
- Search and filtering capabilities