diff --git a/DOCKER.md b/DOCKER.md index 477a2b6..11c22e9 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -4,16 +4,28 @@ This project uses a multi-stage Docker build to create a STDIO version of the ap ## Building with Docker +Run the following command to build with Docker: + ```bash docker build -t postman-api-mcp-stdio . ``` ## Running the Docker container +Select from the following modes to run the Docker container: + +### Minimal mode - 37 Tools (Default) + +This default mode is designed to stay within VS Code's 128 tool limit when combined with other MCP servers. It provides 37 essential tools for common Postman operations: + ```bash docker run -i -e POSTMAN_API_KEY="" postman-api-mcp-stdio ``` -The container will start the MCP server in STDIO mode, suitable for integration with editors and tools like VS Code. +### Full Mode - 106 Tools -For more information about VS Code integration, see the [README](./README.md) file. +This mode includes all 106 available tools with the `--full` flag: + +```bash +docker run -i -e POSTMAN_API_KEY="" postman-api-mcp-stdio --full +``` diff --git a/Dockerfile b/Dockerfile index 456bade..2bf0259 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,11 +4,11 @@ USER app WORKDIR /app -COPY ./package*.json ./ +COPY --chown=app ./package*.json ./ RUN npm ci -COPY . ./ +COPY --chown=app . ./ RUN npm run build @@ -30,6 +30,6 @@ ENV NODE_ENV=production FROM production-base AS production-stdio -ENTRYPOINT ["npm", "run", "start:stdio"] +ENTRYPOINT ["node", "dist/src/index.js"] FROM production-stdio AS production diff --git a/README.md b/README.md index bd2978e..31b2d77 100644 --- a/README.md +++ b/README.md @@ -1,111 +1,146 @@ # Postman MCP Server -**This project offers a single MCP-compatible server option:** +This project offers the following Model Context Protocol (MCP) server options: -- **STDIO server** — A lightweight MCP server that communicates over standard input/output, ideal for integration with editors and tools like [VS Code](https://code.visualstudio.com/). +- [**STDIO**](#stdio) +- [**Streamable HTTP**](#streamable-http) -See more about the Model Context Protocol available transports in the [MCP specification](https://modelcontextprotocol.io/docs/concepts/transports). +For more information about the available transports, see the [MCP specification](https://modelcontextprotocol.io/docs/concepts/transports). -## 🧰 VS Code Integration +## STDIO -> VS Code only supports up to 128 tools. If you add the Postman MCP server and this exceeds 128 tools, you will encounter an issue with your agent. +This is a lightweight solution that's ideal for integration with editors and tools like [VS Code](https://code.visualstudio.com/). -You can integrate your MCP server with Visual Studio Code to use it with VS Code extensions that support MCP. +> For Docker set up and installation, see [DOCKER.md](./DOCKER.md). -1. Create a `.vscode/mcp.json` file in your project with the following configuration: +### VS Code integration + +> **Note:** +> VS Code only supports up to 128 tools. By default, this server provides 37 tools (minimal mode). Use the `--full` flag to access all 106 tools, but note this may exceed VS Code's 128 tool limit when combined with other MCP servers. + +Integrate your MCP server with Visual Studio Code and use it with VS Code extensions that support MCP. To do this, do the following: + +1. Create a *.vscode/mcp.json* file in your project and enter the following: ```json { - "servers": { - "postman-api-mcp": { - "type": "stdio", - "command": "node", - "args": [ - "${workspaceFolder}/dist/src/index.js" - ], - "env": { - "POSTMAN_API_KEY": "${input:postman-api-key}" - } - } - }, - "inputs": [ - { - "id": "postman-api-key", - "type": "promptString", - "description": "Enter your Postman API key" - } - ] + "servers": { + "postman-api-mcp": { + "type": "stdio", + "command": "node", + "args": [ + "${workspaceFolder}/dist/src/index.js" + ], + "env": { + "POSTMAN_API_KEY": "${input:postman-api-key}" + } + } + }, + "inputs": [ + { + "id": "postman-api-key", + "type": "promptString", + "description": "Enter your Postman API key" + } + ] } ``` -2. Install an MCP-compatible VS Code extension (such as GitHub Copilot, Claude for VS Code, or other AI assistants that support MCP). +1. Install an MCP-compatible VS Code extension, such as GitHub Copilot, Claude for VS Code, or other AI assistants that support MCP. -3. Configure your extension to use the MCP server: +#### Configure the extension - - **postman-api-mcp**: Uses the local stdio-based server, running directly from your project files. - - Clone the repository - - In the repository root folder, execute `npm install`. This will install all the required dependencies. - - Make sure to replace `${workspaceFolder}` in the mcp.json file with the full path to the Postman MCP repository. +Configure the extension to use the **postman-api-mcp** server, a local STDIO-based server that runs directly from your project files: -4. When prompted, enter your Postman API key. +1. Clone the **postman-mcp-server** repository. +1. In the repository's root folder, run the `npm install` command. This installs all the required dependencies. +1. Replace `${workspaceFolder}` in the *mcp.json* file with the full path to the Postman MCP repository. +1. When prompted, enter your [Postman API key](https://go.postman.co/settings/me/api-keys). -You can now use your Postman API tools with your VS Code extension through the MCP protocol. +### Claude integration -## 🐳 Docker Setup +To integrate the MCP server with Claude, check the latest [Postman MCP server release](https://github.com/postmanlabs/postman-mcp-server/releases) and get the `.dxt` file. For more information, see Anthropic's [Claude Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions) documentation. -See [DOCKER.md](./DOCKER.md) for up-to-date build, Docker, and usage instructions. +## Streamable HTTP +The streamable HTTP version is available at `https://mcp.postman.com`. It supports two tool configurations to better serve different use cases: -## HTTP streamable version +- **Minimal** — Only includes essential tools for basic Postman operations, available at `https://mcp.postman.com/minimal`. This offers faster performance and simplifies use for those who only need basic Postman operations. +- **Full** — Includes all available Postman API tools (100+ tools), available at `https://mcp.postman.com/mcp`. -If you prefer to use the HTTP version, it's available at https://mcp.postman.com. Here are the instructions to install it: +### Cursor integration -### 🧰 VS Code Integration +To integrate the MCP server with Cursor, click the following button: -``` +[![Install the Postman MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=postman_mcp_server&config=eyJ1cmwiOiJodHRwczovL21jcC5wb3N0bWFuLmNvbS9taW5pbWFsIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ%3D%3D) + +### VS Code integration + +To install in VS Code, add the following to the *.vscode/mcp.json* file: + +```json { "servers": { - "postman-api-http-server": { - "type": "mcp", - "url": "https://mcp.postman.com/mcp", - "headers": { - "Authorization": "Bearer ${input:postman-api-key}" - } - } + "postman-api-http-server": { + "type": "sse", + "url": "https://mcp.postman.com/mcp", + "headers": { + "Authorization": "Bearer ${input:postman-api-key}" + } + } }, "inputs": [ - { - "id": "postman-api-key", - "type": "promptString", - "description": "Enter your Postman API key" - } + { + "id": "postman-api-key", + "type": "promptString", + "description": "Enter your Postman API key" + } ] - } +} ``` -You will be asked to input your Postman API key. Afterwards, the agent performs calls to the Postman cloud MCP server (https://mcp.postman.com). +When prompted, enter your Postman API key. Afterwards, the agent performs calls to the Postman cloud MCP server at `https://mcp.postman.com`. -### 🧰 Claude Integration +### Tool configuration modes -Open the *claude_desktop_config.json* file, which is accessible from Claude preferences. Then, add the following: +- **Minimal mode** - Provides 37 essential tools for common Postman operations. +- **Full mode** - Add `--full` to the `args` array to access all 106 available tools. -``` +The following example demonstrates how to enable full mode in VS Code: + +```json { - "mcpServers": { - "postman-api": { - "command": "npx", - "args": [ - "mcp-remote", - "https://mcp.postman-beta.com/mcp", - "--header", - "Authorization: Bearer PMAK-YOUR-POSTMAN-API-KEY" - ] - } - } + "servers": { + "postman-api-http-server": { + "type": "sse", + "url": "https://mcp.postman.com/{minimal | mcp}", // choose "minimal" or "mcp" + "headers": { + "Authorization": "Bearer ${input:postman-api-key}" + } + } + }, + "inputs": [ + { + "id": "postman-api-key", + "type": "promptString", + "description": "Enter your Postman API key" + } + ] } ``` -## 💬 Questions and support +## Migration from v1.x to v2.x + +- **Tool naming changes** - All tool names changed from kebab-case to camelCase. For example: + - `create-collection` → `createCollection` + - `get-workspaces` → `getWorkspaces` + - `delete-environment` → `deleteEnvironment` +- **Tool availability changes** + - The default (Minimal) behavior provides only 37 essential tools. + - Minimal mode is designed to stay within VS Code's 128 tool limit when combined with other MCP servers. + - The `--full` flag provides access to all 106 tools. + +## Questions and support - See the [Postman Agent Generator](https://postman.com/explore/agent-generator) page for updates and new capabilities. - See [Add your MCP requests to your collections](https://learning.postman.com/docs/postman-ai-agent-builder/mcp-requests/overview/) to learn how to use Postman to perform MCP requests. diff --git a/dist/package.json b/dist/package.json index 975ba98..db933b6 100644 --- a/dist/package.json +++ b/dist/package.json @@ -5,8 +5,6 @@ "main": "index.js", "type": "module", "scripts": { - "start": "node dist/src/index.js --sse", - "start:dev": "tsx src/index.ts --sse", "start:stdio": "node dist/src/index.js", "build": "eslint --fix ./src && prettier --write \"src/**/*.ts\" && tsc", "test": "vitest", diff --git a/package.json b/package.json index 3ff2864..20ab5c3 100644 --- a/package.json +++ b/package.json @@ -5,8 +5,6 @@ "main": "index.js", "type": "module", "scripts": { - "start": "node dist/src/index.js --sse", - "start:dev": "tsx src/index.ts --sse", "start:stdio": "node dist/src/index.js", "build": "eslint --fix ./src && prettier --write \"src/**/*.ts\" && tsc", "test": "vitest",