POEditor MCP Server

# Installation Guide This guide will help you install and configure the POEditor MCP Server. ## Prerequisites - Python 3.8 or higher - pip (Python package installer) - A POEditor account with API access ## Quick Installation ### Option 1: Automatic Setup (Recommended) Run the automatic setup script that will handle everything for you: ```bash python setup.py ``` This script will: - Check system requirements - Install all dependencies - Create necessary directories - Guide you through configuration - Test the installation ### Option 2: Manual Installation If you prefer to install manually: 1. **Clone or download the repository** ```bash git clone <repository-url> cd poeditor-mcp ``` 2. **Install dependencies** ```bash pip install -r requirements.txt ``` 3. **Create environment file** ```bash cp .env.template .env ``` 4. **Edit the .env file with your settings** ```bash nano .env # or use your preferred editor ``` 5. **Create necessary directories** ```bash mkdir -p logs reports exports backups ``` ## Configuration ### Required Settings Edit your `.env` file and set these required values: ```env # POEditor API Configuration POEDITOR_API_TOKEN=your_actual_api_token_here # JIRA Integration (Optional) JIRA_BASE_URL=https://your-domain.atlassian.net JIRA_EMAIL=your-email@example.com JIRA_API_TOKEN=your_jira_api_token JIRA_PROJECT_KEY=POE ``` ### Optional Settings You can also configure these optional settings: ```env # Logging LOG_LEVEL=INFO # Export Settings DEFAULT_EXPORT_FORMAT=json EXPORT_DIRECTORY=./exports # Email Notifications (optional) SMTP_SERVER=smtp.gmail.com SMTP_PORT=587 SMTP_USERNAME=your_email@gmail.com SMTP_PASSWORD=your_app_password ``` ### Getting Your POEditor API Token 1. Log in to your POEditor account 2. Go to Account Settings → API Access 3. Generate a new API token 4. Copy the token to your `.env` file ## Testing the Installation ### Test the MCP Server Run the basic usage example: ```bash python examples/basic_usage.py ``` ### Test with Claude Desktop 1. Add the server to your Claude Desktop configuration: ```json { "mcpServers": { "poeditor": { "command": "python", "args": ["-m", "mcp_poeditor"], "cwd": "/path/to/poeditor-mcp" } } } ``` 2. Restart Claude Desktop 3. The POEditor tools should now be available ## Troubleshooting ### Common Issues **API Token Error:** - Verify your API token is correct - Check that your POEditor account has API access enabled **Permission Errors:** - Make sure you have write permissions in the project directory - On Unix systems, you may need to make scripts executable: ```bash chmod +x examples/basic_usage.py ``` **Module Import Errors:** - Ensure all dependencies are installed: `pip install -r requirements.txt` - Check your Python version: `python --version` **Connection Issues:** - Verify your internet connection - Check if POEditor API is accessible from your network ### Getting Help If you encounter issues: 1. Check the logs in the `logs/` directory 2. Run the setup script again: `python setup.py` 3. Review the [troubleshooting section](README.md#troubleshooting) in the main README 4. Create an issue on the project repository ## Next Steps After successful installation: 1. **Explore Examples**: Check the `examples/` directory for usage patterns 2. **Read Documentation**: Review the main [README.md](../README.md) for detailed features 3. **Configure Automation**: Set up the automation scripts in the `scripts/` directory 4. **Customize Settings**: Adjust configuration in `.env` for your needs ## Updating To update to a newer version: 1. **Backup your configuration**: ```bash cp .env .env.backup ``` 2. **Pull latest changes** (if using git): ```bash git pull origin main ``` 3. **Update dependencies**: ```bash pip install -r requirements.txt --upgrade ``` 4. **Run setup again if needed**: ```bash python setup.py ``` ## MCP Client Configuration After installation, you need to configure your MCP client to use the POEditor server. ### Claude Desktop Configuration Add the following to your Claude Desktop configuration file: **macOS/Linux**: `~/.claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "poeditor": { "command": "python", "args": ["-m", "mcp_poeditor"], "cwd": "/absolute/path/to/your/poeditor-mcp", "env": { "POEDITOR_API_TOKEN": "your_poeditor_token_here" } } } } ``` ### Visual Studio Code Configuration Add the following to your VS Code settings: **Workspace Settings**: Create or edit `.vscode/settings.json` in your workspace: ```json { "mcp.servers": { "poeditor": { "command": "python", "args": ["-m", "mcp_poeditor"], "cwd": "/absolute/path/to/your/poeditor-mcp", "env": { "POEDITOR_API_TOKEN": "your_poeditor_token_here" } } } } ``` **User Settings**: Alternatively, add to your global VS Code settings via `Cmd/Ctrl + ,` → Open Settings JSON. ### Configuration Templates Use the provided example files as templates: - `claude_desktop_config_example.json` - For Claude Desktop - `vscode_settings_example.json` - For Visual Studio Code ### Important Notes 1. **Replace paths**: Update `/absolute/path/to/your/poeditor-mcp` with your actual installation path 2. **API Token**: Replace `your_poeditor_token_here` with your actual POEditor API token 3. **Restart clients**: Restart your MCP client after configuration changes 4. **Verify setup**: Use the test commands to verify everything works correctly