|
| 1 | +# Gitpod MCP Server |
| 2 | + |
| 3 | +A Modal Context Protocol (MCP) server that enables Claude Desktop to interact with Gitpod's API. This integration allows Claude to create Gitpod environments, check identity information, and perform other Gitpod-related tasks directly through natural language commands. |
| 4 | + |
| 5 | +## 🌟 Features |
| 6 | + |
| 7 | +- 🔐 **Secure Authentication**: Uses Gitpod API tokens for secure access |
| 8 | +- 🔄 **Real-time Integration**: Direct integration with Gitpod's API |
| 9 | +- 🤖 **Natural Language Interface**: Interact with Gitpod using natural language through Claude |
| 10 | +- 📝 **Comprehensive Logging**: Detailed logging for debugging and monitoring |
| 11 | +- 🚀 **Environment Management**: Create and manage Gitpod environments easily |
| 12 | +- ⚡ **Command Execution**: Run commands in your environments directly |
| 13 | + |
| 14 | +## 🚀 Available Tools |
| 15 | + |
| 16 | +1. **get-identity** |
| 17 | + |
| 18 | + - Get authenticated identity information from Gitpod |
| 19 | + - No additional parameters required |
| 20 | + |
| 21 | +2. **create-environment** |
| 22 | + |
| 23 | + - Create a new Gitpod environment from a repository URL |
| 24 | + - Optional parameter: `repository_url` (defaults to https://github.com/gitpod-io/empty) |
| 25 | + |
| 26 | +3. **create-environment-with-command** |
| 27 | + - Create a new Gitpod environment and run a command in it |
| 28 | + - Required parameter: `command` (command to run in the environment) |
| 29 | + - Optional parameter: `repository_url` (defaults to https://github.com/gitpod-io/empty) |
| 30 | + |
| 31 | +## 📋 Prerequisites |
| 32 | + |
| 33 | +- Python 3.11 or higher |
| 34 | +- Claude Desktop application |
| 35 | +- Gitpod flex account and Personal Access Token |
| 36 | +- `uv` package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`) |
| 37 | + |
| 38 | +## ⚙️ Installation |
| 39 | + |
| 40 | +1. Clone the repository: |
| 41 | + |
| 42 | +```bash |
| 43 | +git clone https://github.com/gitpod-io/gitpod-sdk-python |
| 44 | +cd gitpod-sdk-python/examples/mcp-server |
| 45 | +``` |
| 46 | + |
| 47 | +2. Install dependencies: |
| 48 | + |
| 49 | +```bash |
| 50 | +uv sync |
| 51 | +``` |
| 52 | + |
| 53 | +## 🔑 Configuration |
| 54 | + |
| 55 | +1. Get your Gitpod API token: |
| 56 | + |
| 57 | + - Go to [Gitpod Flex Dashboard](https://app.gitpod.io/settings/personal-access-tokens) → Settings → Personal access tokens |
| 58 | + |
| 59 | +2. Configure Claude Desktop: |
| 60 | + Create or update `~/Library/Application\ Support/Claude/claude_desktop_config.json`: |
| 61 | + |
| 62 | + ```json |
| 63 | + { |
| 64 | + "mcpServers": { |
| 65 | + "gitpod-mcp": { |
| 66 | + "command": "/path/to/uv", |
| 67 | + "args": [ |
| 68 | + "--directory", |
| 69 | + "/path/to/gitpod-sdk-python/examples/mcp-server", |
| 70 | + "run", |
| 71 | + "server.py" |
| 72 | + ], |
| 73 | + "env": { |
| 74 | + "GITPOD_LOG": "info", |
| 75 | + "GITPOD_API_KEY": "your-gitpod-api-token-here" |
| 76 | + } |
| 77 | + } |
| 78 | + } |
| 79 | + } |
| 80 | + ``` |
| 81 | + |
| 82 | +## 🎯 Usage Examples |
| 83 | + |
| 84 | +Here are some ways you can interact with the MCP server through Claude: |
| 85 | + |
| 86 | +1. Check your Gitpod identity: |
| 87 | + |
| 88 | + ``` |
| 89 | + "Get my Gitpod identity" |
| 90 | + ``` |
| 91 | + |
| 92 | +2. Create a new environment: |
| 93 | + |
| 94 | + ``` |
| 95 | + "Create a Gitpod environment" |
| 96 | + "Create a Gitpod environment for https://github.com/my/repo" |
| 97 | + ``` |
| 98 | + |
| 99 | +3. Create an environment and run a command: |
| 100 | + ``` |
| 101 | + "Create a Gitpod environment and run 'echo Hello World'" |
| 102 | + "Create an environment from https://github.com/my/repo and run 'npm install'" |
| 103 | + ``` |
| 104 | + |
| 105 | +## 🔍 Troubleshooting |
| 106 | + |
| 107 | +The server logs all activities to `gitpod_mcp.log` in the project directory. Common issues: |
| 108 | + |
| 109 | +1. **Authentication Errors** |
| 110 | + |
| 111 | + - Verify your Gitpod API token is valid |
| 112 | + - Check if the token has the required scopes |
| 113 | + - Look for authentication errors in the log |
| 114 | + |
| 115 | +2. **Environment Creation Issues** |
| 116 | + |
| 117 | + - Ensure the repository URL is accessible |
| 118 | + - Check if you have an environment class available |
| 119 | + - Verify your Gitpod account has available resources |
| 120 | + |
| 121 | +3. **Command Execution Problems** |
| 122 | + - Make sure the command is valid for the environment |
| 123 | + - Check if the environment is fully initialized |
| 124 | + - Look for command execution errors in the logs |
0 commit comments