Skip to content
This repository was archived by the owner on Feb 24, 2026. It is now read-only.

Commit 6a7a5ef

Browse files
Matanga1-2Matanga1-2
authored
Merge pull request #22 from port-labs/update-readme-installation-methods
Docs: Overhaul README with updated installation and usage instructions
1 parent c042c91 commit 6a7a5ef

File tree

3 files changed

+215
-45
lines changed

3 files changed

+215
-45
lines changed

‎README.md‎

Lines changed: 215 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
# Port MCP Server
22

3-
A Model Context Protocol (MCP) server for the [Port.io API](https://www.getport.io/), enabling Claude to interact with Port.io's developer platform capabilities using natural language.
3+
The [Port IO](https://www.getport.io/) MCP server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server, enabling advanced automations and natual language interactions for developers and AI applications.
44

55
## What You Can Do With Port MCP
66

7-
Transform how you work with Port.io using natural language:
8-
97
### Find Information Quickly
108
- **Get entity details** - "Who is the owner of service X?"
119
- **Check on-call status** - "Who is on call right now?"
@@ -23,24 +21,61 @@ Transform how you work with Port.io using natural language:
2321

2422
We're continuously expanding Port MCP's capabilities. Have a suggestion? We'd love to hear your feedback on our [roadmap](https://roadmap.getport.io/ideas)!
2523

26-
## Installation
2724

28-
### Obtain your Port credentials
29-
1. Create a Port.io Account:
30-
- Visit [Port.io](https://www.port.io/)
31-
- Sign up for an account if you don't have one
25+
# Installation
26+
27+
## Prerequisites
28+
Before you begin, you'll need:
3229

33-
2. Create an API Key:
34-
- Navigate to your Port.io dashboard
30+
1. Create a Port Account (if you don't have one):
31+
- Visit [Port.io](https://app.port.io/)
32+
- Sign up for an account
33+
34+
2. Obtain Port Credentials:
35+
- Navigate to your Port dashboard
3536
- Go to Settings > Credentials
3637
- Save both the Client ID and Client Secret
3738

38-
### Claude Desktop
39+
3. Installation Requirements:
40+
- Either [Docker](https://www.docker.com/get-started/) installed on your system
41+
- OR [uvx](https://pypi.org/project/uvx/) package manager installed
42+
43+
>[!NOTE]
44+
>You will also need to provide your Port region, which is either EU or US. If not provided, the default is EU.
45+
46+
## Installation methods
47+
Port MCP Server can be installed using two methods:
48+
49+
### Package Installation (uvx)
50+
Use our official [Port MCP server](https://pypi.org/project/mcp-server-port/) package.
51+
52+
### Docker Installation
53+
Use our official Docker image:
54+
```bash
55+
docker pull ghcr.io/port-labs/port-mcp-server:0.2.8
56+
```
57+
58+
### Additional configurations
59+
You can pass these additional arguments for more advanced configuration:
60+
61+
| Configuration Parameter | UVX Flag | Docker Environment Variable | Description | Default Value |
62+
|------------------------|----------|---------------------------|-------------|---------------|
63+
| Log Level | `log-level` | `PORT_LOG_LEVEL` | Controls the level of log output | `ERROR` |
64+
| API Validation | `api-validation-enabled` | `PORT_API_VALIDATION_ENABLED` | Controls if API schema should be validated and fail if it's not valid | `False` |
65+
66+
## Usage with Claude Desktop
67+
1. Go to Settings > Developer and click on "Edit config".
68+
2. Edit the `claude_desktop_config.json` file and add the below configuration based on the installation method.
69+
3. Save the file and restart Claude.
70+
4. In a new chat, check the Tools section and you'll see Port available tools.
71+
72+
![Claude MCP Tools](/assets/claude_mcp_tools.png)
3973

40-
Add the following to your `claude_desktop_config.json`:
74+
### Docker
4175

76+
>[!TIP]
77+
>Consider using the full path to Docker (e.g., `/usr/local/bin/docker`) instead of just `docker`. You can find this path by running `which docker` in your terminal. Using the full path helps avoid PATH resolution issues and ensures consistent behavior across different shell environments.
4278
43-
#### Docker
4479
```json
4580
{
4681
"mcpServers": {
@@ -58,7 +93,7 @@ Add the following to your `claude_desktop_config.json`:
5893
"PORT_REGION",
5994
"-e",
6095
"PORT_LOG_LEVEL",
61-
"ghcr.io/port-labs/port-mcp-server:0.2.1"
96+
"ghcr.io/port-labs/port-mcp-server:0.2.2"
6297
],
6398
"env": {
6499
"PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
@@ -71,25 +106,58 @@ Add the following to your `claude_desktop_config.json`:
71106
}
72107
```
73108

109+
### uvx
74110

75-
### Cursor
111+
>[!NOTE]
112+
>If you want to run the command from a virtual Python environment, add a `PYTHONPATH` variable to the `env` object with its path, e.g., `/path/to/your/venv/bin/python`.
76113
77-
Configure in Cursor settings:
78-
- Go to Cursor settings > MCP Servers
79-
- Configure with:
80-
* Name - `Port`
81-
* Type - `Command`
82-
* Command - `/path/to/your/file/run-port-mcp.sh`
114+
```json
115+
{
116+
"mcpServers": {
117+
"Port": {
118+
"command": "uvx",
119+
"args": [
120+
"mcp-server-port@0.2.8",
121+
"--client-id",
122+
"<PORT_CLIENT_ID>",
123+
"--client-secret",
124+
"<PORT_CLIENT_SECRET>",
125+
"--region",
126+
"<PORT_REGION>"
127+
],
128+
"env": {
129+
"PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
130+
"PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
131+
"PORT_REGION": "<PORT_REGION>",
132+
"PYTHONPATH": "/Users/matangrady/.venv-port-mcp/bin/python"
133+
}
134+
}
135+
}
136+
}
137+
```
138+
139+
## Usage with Cursor
140+
141+
1. Go to Cursor > Settings > Cursor Settings.
142+
2. Click on the MCP tab, and "Add new global MCP server".
143+
2. Edit the `mcp.json` file and add the below configuration based on the installation method.
144+
3. Save the file and return to Cursor Settings.
145+
4. You will see the new Port server and its available tools.
83146

84-
####Docker
147+
![Cursor MCP Screenshot](/assets/cursor_mcp_screenshot.png)
148+
149+
### Docker
150+
151+
>[!TIP]
152+
>Consider using the full path to Docker (e.g., `/usr/local/bin/docker`) instead of just `docker`. You can find this path by running `which docker` in your terminal. Using the full path helps avoid PATH resolution issues and ensures consistent behavior across different shell environments.
85153
86154
```json
87155
{
88-
"mcpServers": {
89-
"port": {
90-
"command": "docker",
91-
"args": [
92-
"run",
156+
"mcpServers": {
157+
"port": {
158+
"command": "docker",
159+
"args": [
160+
"run",
93161
"-i",
94162
"--rm",
95163
"-e",
@@ -100,24 +168,126 @@ Configure in Cursor settings:
100168
"PORT_REGION",
101169
"-e",
102170
"PORT_LOG_LEVEL",
103-
"ghcr.io/port-labs/port-mcp-server:0.2.1"
104-
],
105-
"env": {
171+
"ghcr.io/port-labs/port-mcp-server:0.2.2"
172+
],
173+
"env": {
106174
"PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
107175
"PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
108176
"PORT_REGION": "<PORT_REGION>",
109177
"PORT_LOG_LEVEL": "<PORT_LOG_LEVEL>"
110-
}
111-
}
178+
}
112179
}
180+
}
113181
}
114182
```
115-
![Cursor MCP Screenshot](/assets/cursor_mcp_screenshot.png)
116183

117184

118-
## Available Tools
119185

120-
### Blueprint Tools
186+
### uvx
187+
>[!NOTE]
188+
>If you want to run the command from a virtual Python environment, add a `PYTHONPATH` variable to the `env` object with its path, e.g., `/path/to/your/venv/bin/python`.
189+
190+
```json
191+
{
192+
"mcpServers": {
193+
"Port": {
194+
"command": "uvx",
195+
"args": [
196+
"mcp-server-port@0.2.8",
197+
"--client-id",
198+
"<PORT_CLIENT_ID>",
199+
"--client-secret",
200+
"<PORT_CLIENT_SECRET>",
201+
"--region",
202+
"<PORT_REGION>"
203+
],
204+
"env": {
205+
"PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
206+
"PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
207+
"PORT_REGION": "<PORT_REGION>",
208+
"PYTHONPATH": "/Users/matangrady/.venv-port-mcp/bin/python"
209+
}
210+
}
211+
}
212+
}
213+
```
214+
215+
### Usage with VS Code
216+
217+
>[!TIP]
218+
>VS Code can automatically discover MCP servers already installed in Cursor and Claude.
219+
220+
>[!NOTE]
221+
>For quick installation, use the one-click install buttons and select where to add the MCP configuration. Make sure to replace the placeholders with your Port credentials.
222+
223+
[Docker quick installation](https://insiders.vscode.dev/redirect/mcp/install?name=port&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22PORT_CLIENT_ID%22%2C%22-e%22%2C%22PORT_CLIENT_SECRET%22%2C%22-e%22%2C%22PORT_REGION%22%2C%22ghcr.io%2Fport-labs%2Fport-mcp-server%3A0.2.2%22%5D%2C%22env%22%3A%7B%22PORT_CLIENT_ID%22%3A%22%3CPORT_CLIENT_ID%3E%22%2C%22PORT_CLIENT_SECRET%22%3A%22%3CPORT_CLIENT_SECRET%3E%22%2C%22PORT_REGION%22%3A%22%3CPORT_REGION%3E%22%7D%7D)
224+
[uvx quick installation](https://insiders.vscode.dev/redirect/mcp/install?name=port&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-port%400.2.8%22%2C%22--client-id%22%2C%22%3CPORT_CLIENT_ID%3E%22%2C%22--client-secret%22%2C%22%3CPORT_CLIENT_SECRET%3E%22%2C%22--region%22%2C%22%3CPORT_REGION%3E%22%5D%2C%22env%22%3A%7B%22PORT_CLIENT_ID%22%3A%22%3CPORT_CLIENT_ID%3E%22%2C%22PORT_CLIENT_SECRET%22%3A%22%3CPORT_CLIENT_SECRET%3E%22%2C%22PORT_REGION%22%3A%22%3CPORT_REGION%3E%22%7D%7D)
225+
226+
For manual installation follow these steps:
227+
1. Go to the Command Palette by pressing `Cmd + Shift + P` / `Ctrl + Shift + P`.
228+
2. Type `Preferences: Open User Settings (JSON)` and press enter.
229+
2. Edit the `settings.json` file and add the below configuration under the `mcp`>`servers`.
230+
3. Use Copilot in Agent mode, make sure the server is running and see its available Port tools.
231+
232+
![VS Code MCP Tools](/assets/vs_code_mcp_tools.png)
233+
234+
### Docker
235+
>[!TIP]
236+
>Consider using the full path to Docker (e.g., `/usr/local/bin/docker`) instead of just `docker`. You can find this path by running `which docker` in your terminal. Using the full path helps avoid PATH resolution issues and ensures consistent behavior across different shell environments.
237+
238+
```json
239+
"Port": {
240+
"type": "stdio",
241+
"command": "docker",
242+
"args": [
243+
"run",
244+
"-i",
245+
"--rm",
246+
"-e",
247+
"PORT_CLIENT_ID",
248+
"-e",
249+
"PORT_CLIENT_SECRET",
250+
"-e",
251+
"PORT_REGION",
252+
"ghcr.io/port-labs/port-mcp-server:0.2.2"
253+
],
254+
"env": {
255+
"PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
256+
"PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
257+
"PORT_REGION": "<PORT_REGION>"
258+
}
259+
}
260+
```
261+
262+
### uvx
263+
264+
>[!NOTE]
265+
>If you want to run the command from a virtual Python environment, add a `PYTHONPATH` variable to the `env` object with its path, e.g., `/path/to/your/venv/bin/python`.
266+
267+
```json
268+
"Port": {
269+
"type": "stdio",
270+
"command": "uvx",
271+
"args": [
272+
"mcp-server-port@0.2.8",
273+
"--client-id",
274+
"<PORT_CLIENT_ID>",
275+
"--client-secret",
276+
"<PORT_CLIENT_SECRET>",
277+
"--region",
278+
"<PORT_REGION>"
279+
],
280+
"env": {
281+
"PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
282+
"PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
283+
"PORT_REGION": "<PORT_REGION>"
284+
}
285+
}
286+
```
287+
288+
# Available Tools
289+
290+
## Blueprint Tools
121291

122292
1. `get_blueprints`
123293
- Retrieve a list of all blueprints from Port
@@ -151,7 +321,7 @@ Configure in Cursor settings:
151321
- `blueprint_identifier` (string): The unique identifier of the blueprint to delete
152322
- Returns: Success status
153323

154-
### Entity Tools
324+
## Entity Tools
155325

156326
1. `get_entities`
157327
- Retrieve all entities for a given blueprint
@@ -189,7 +359,7 @@ Configure in Cursor settings:
189359
- Optional inputs:
190360
- `delete_dependents` (boolean, default: false): If true, also deletes all dependencies
191361

192-
### Scorecard Tools
362+
## Scorecard Tools
193363

194364
1. `get_scorecards`
195365
- Retrieve all scorecards from Port
@@ -228,25 +398,25 @@ Configure in Cursor settings:
228398
- `scorecard_identifier` (string): The unique identifier of the scorecard to delete
229399
- Returns: Success status
230400

231-
### AI Agent Tool
401+
## AI Agents Tool
232402

233403
1. `invoke_ai_agent`
234404
- Invoke a Port AI agent with a specific prompt
235405
- Required inputs:
236406
- `prompt` (string): The prompt to send to the AI agent
237407
- Returns: Invocation status and message from the AI agent
238408

239-
## Feedback and Roadmap
409+
# Feedback and Roadmap
240410

241411
We're continuously improving Port MCP and would love to hear from you! Please share your feedback and feature requests on our [roadmap page](https://roadmap.getport.io/ideas).
242412

243-
## Troubleshooting
413+
# Troubleshooting
244414

245415
If you encounter authentication errors, verify that:
246-
1. Your Port credentials are correctly set in the arguments
247-
2. You have the necessary permissions
248-
3. The credentials are properly copied to your configuration
416+
1. Your Port credentials are correctly set in the arguments.
417+
2. You have the necessary permissions.
418+
3. The credentials are properly copied to your configuration.
249419

250-
## License
420+
# License
251421

252-
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
422+
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the [MIT License](https://github.com/port-labs/port-mcp-server/blob/main/LICENSE).

‎assets/claude_mcp_tools.png‎

120 KB
Loading

‎assets/vs_code_mcp_tools.png‎

168 KB
Loading

0 commit comments

Comments
 (0)