Port MCP server for AI agents

The Port IO MCP server provides a Model Context Protocol implementation that allows AI assistants to interact with Port's developer portal, enabling advanced automations and natural language interactions with your software catalog data. Through the MCP server, you can query information, analyze scorecards, create resources, and manage permissions directly from AI tools.

Installation

Prerequisites

Before installing the Port MCP server, you'll need:

A Port account (sign up at Port.io if you don't have one)
Port credentials (Client ID and Client Secret) from your Port dashboard under Settings > Credentials
Either Docker or the uvx package manager installed on your system
Your Port region (EU or US, defaults to EU if not specified)

Installation Methods

Docker Installation

docker pull ghcr.io/port-labs/port-mcp-server:latest

Package Installation with uvx

Create and activate a Python virtual environment (recommended)

python -m venv venv
source venv/bin/activate  # On Linux/macOS
# OR
venv\Scripts\activate  # On Windows

Install the UV package manager

# Using Homebrew
brew install uv

# Or using pip
pip install uv

Set required environment variables

export PORT_CLIENT_ID="your_port_client_id"
export PORT_CLIENT_SECRET="your_port_client_secret"
export PORT_REGION="EU"  # or "US"

Run the MCP server

uvx mcp-server-port --client-id your_port_client_id --client-secret your_port_client_secret --region EU --log-level DEBUG

Additional Configuration

You can use these additional parameters for more advanced configuration:

Parameter	UVX Flag	Docker Environment Variable	Description	Default
Log Level	`log-level`	`PORT_LOG_LEVEL`	Controls log output level	`ERROR`
API Validation	`api-validation-enabled`	`PORT_API_VALIDATION_ENABLED`	Controls if API schema should be validated	`False`

Usage with AI Tools

Claude Desktop

Go to Settings > Developer and click "Edit config"
Edit the claude_desktop_config.json file with one of these configurations:

Docker configuration:

{
  "mcpServers": {
    "port": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PORT_CLIENT_ID",
        "-e",
        "PORT_CLIENT_SECRET",
        "-e",
        "PORT_REGION",
        "-e",
        "PORT_LOG_LEVEL",
        "ghcr.io/port-labs/port-mcp-server:latest"
      ],
      "env": {
        "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
        "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
        "PORT_REGION": "<PORT_REGION>",
        "PORT_LOG_LEVEL": "<PORT_LOG_LEVEL>"
      }
    }
  }
}

uvx configuration:

{
  "mcpServers": {
    "Port": {
      "command": "uvx",
      "args": [
        "[email protected]",
        "--client-id",
        "<PORT_CLIENT_ID>",
        "--client-secret",
        "<PORT_CLIENT_SECRET>",
        "--region",
        "<PORT_REGION>"
      ],
      "env": {
        "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
        "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
        "PORT_REGION": "<PORT_REGION>",
        "PYTHONPATH": "/Users/matangrady/.venv-port-mcp/bin/python"
      }
    }
  }
}

Cursor

Go to Cursor > Settings > Cursor Settings
Click on the MCP tab, and "Add new global MCP server"
Add either the Docker or uvx configuration from above
Save the file and return to Cursor Settings

VS Code

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Type Preferences: Open User Settings (JSON) and press enter
Add one of these configurations under the mcp > servers section:

Docker configuration:

"Port": {
  "type": "stdio",
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "PORT_CLIENT_ID",
    "-e",
    "PORT_CLIENT_SECRET",
    "-e",
    "PORT_REGION",
    "ghcr.io/port-labs/port-mcp-server:latest"
  ],
  "env": {
    "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
    "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
    "PORT_REGION": "<PORT_REGION>"
  }
}

uvx configuration:

"Port": {
  "type": "stdio",
  "command": "uvx",
  "args": [
    "[email protected]",
    "--client-id",
    "<PORT_CLIENT_ID>",
    "--client-secret",
    "<PORT_CLIENT_SECRET>",
    "--region",
    "<PORT_REGION>"
  ],
  "env": {
    "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
    "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
    "PORT_REGION": "<PORT_REGION>"
  }
}

Neovim (mcphub.nvim)

Install the mcphub.nvim plugin
Access the servers config with :MCPHub and navigate to Config tab
Add the configuration for Port MCP Server under the mcpServers section (similar to above examples)
Set your PORT_CLIENT_ID and PORT_CLIENT_SECRET environment variables
Restart the servers with :MCPHub and trigger restart with R

Available Tools

Blueprint Tools

get_blueprints: List all blueprints
get_blueprint: Get details for a specific blueprint
create_blueprint: Create a new blueprint
update_blueprint: Update an existing blueprint
delete_blueprint: Delete a blueprint

Entity Tools

get_entities: List all entities for a blueprint
get_entity: Get details for a specific entity
create_entity: Create a new entity
update_entity: Update an existing entity
delete_entity: Delete an entity

Scorecard Tools

get_scorecards: List all scorecards
get_scorecard: Get details for a specific scorecard
create_scorecard: Create a new scorecard
update_scorecard: Update an existing scorecard
delete_scorecard: Delete a scorecard

AI Agents Tool

invoke_ai_agent: Invoke a Port AI agent with a specific prompt

Troubleshooting

If you encounter authentication errors:

Verify your Port credentials are correctly set in the arguments
Confirm you have the necessary permissions
Check that the credentials are properly copied to your configuration

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "port" '{"command":"docker","args":["run","-i","--rm","-e","PORT_CLIENT_ID","-e","PORT_CLIENT_SECRET","-e","PORT_REGION","-e","PORT_LOG_LEVEL","ghcr.io/port-labs/port-mcp-server:latest"],"env":{"PORT_CLIENT_ID":"<PORT_CLIENT_ID>","PORT_CLIENT_SECRET":"<PORT_CLIENT_SECRET>","PORT_REGION":"<PORT_REGION>","PORT_LOG_LEVEL":"<PORT_LOG_LEVEL>"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "port": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "PORT_CLIENT_ID",
                "-e",
                "PORT_CLIENT_SECRET",
                "-e",
                "PORT_REGION",
                "-e",
                "PORT_LOG_LEVEL",
                "ghcr.io/port-labs/port-mcp-server:latest"
            ],
            "env": {
                "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
                "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
                "PORT_REGION": "<PORT_REGION>",
                "PORT_LOG_LEVEL": "<PORT_LOG_LEVEL>"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "port": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "PORT_CLIENT_ID",
                "-e",
                "PORT_CLIENT_SECRET",
                "-e",
                "PORT_REGION",
                "-e",
                "PORT_LOG_LEVEL",
                "ghcr.io/port-labs/port-mcp-server:latest"
            ],
            "env": {
                "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
                "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
                "PORT_REGION": "<PORT_REGION>",
                "PORT_LOG_LEVEL": "<PORT_LOG_LEVEL>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect