# Postman MCP Generator

Welcome to your enhanced MCP server! 🚀 This project was created with the [Postman MCP Generator](https://postman.com/explore/mcp-generator) and enhanced with a modern web interface. It provides you with:

- ✅ An MCP-compatible server (`mcpServer.js`)
- ✅ Automatically generated JavaScript tools for each selected Postman API request
- ✅ **NEW**: Modern web-based frontend interface with real-time capabilities
- ✅ **NEW**: Server-Sent Events (SSE) and HTTP streaming support
- ✅ Multiple connection modes: STDIO, SSE, and HTTP
- ✅ **NEW**: Interactive tool execution with live results
- ✅ **NEW**: Session management and activity logging

Let's set things up!

## 🚦 Getting Started

### ⚙️ Prerequisites

Before starting, please ensure you have:

- [Node.js (v18+ required, v20+ recommended)](https://nodejs.org/)
- [npm](https://www.npmjs.com/) (included with Node)

Warning: if you run with a lower version of Node, `fetch` won't be present. Tools use `fetch` to make HTTP calls. To work around this, you can modify the tools to use `node-fetch` instead. Make sure that `node-fetch` is installed as a dependency and then import it as `fetch` into each tool file.

### 📥 Installation & Setup

**1. Install dependencies**

Run from your project's root directory:

```sh
npm install
```

### 🔐 Set tool environment variables

In the `.env` file, you'll see environment variable placeholders, one for each workspace that the selected tools are from. For example, if you selected requests from 2 workspaces, e.g. Acme and Widgets, you'll see two placeholders:

```
ACME_API_KEY=
WIDGETS_API_KEY=
```

Update the values with actual API keys for each API. These environment variables are used inside of the generated tools to set the API key for each request. You can inspect a file in the `tools` directory to see how it works.

```javascript
// environment variables are used inside of each tool file
const apiKey = process.env.ACME_API_KEY;
```

**Caveat:** This may not be correct for every API. The generation logic is relatively simple - for each workspace, we create an environment variable with the same name as the workspace slug, and then use that environment variable in each tool file that belongs to that workspace. If this isn't the right behavior for your chosen API, no problem! You can manually update anything in the `.env` file or tool files to accurately reflect the API's method of authentication.

## 🌐 Web Interface

The server includes a comprehensive web-based interface that provides:

- **Interactive Tool Execution**: Select and execute Facebook Marketing API tools with a professional interface
- **Real-time Connection Status**: Monitor your connection to the MCP server
- **Multiple Connection Types**: Choose between SSE (Server-Sent Events) and HTTP streaming
- **Live Results Display**: View tool execution results in real-time
- **Activity Logging**: Track all server activities and tool executions
- **Export Functionality**: Export results for further analysis
- **Session Management**: Handle multiple concurrent connections
- **Professional UI**: Clean, responsive design with Facebook branding

### Starting the Web Interface

```sh
# Start the web server (recommended)
npm start

# Or for development with auto-reload
npm run dev
```

Then open your browser to `http://localhost:3001` to access the modern web interface.

### Web Interface Features

- **Tool Browser**: Browse all available Facebook Marketing API tools
- **Parameter Forms**: Dynamic forms for tool parameters with validation
- **Real-time Execution**: Execute tools and see results instantly
- **Connection Management**: Switch between SSE and HTTP modes
- **Export Results**: Download execution results as JSON
- **Activity Logs**: Monitor all server activities and errors

### Available Server Modes

```sh
# Web interface with SSE and HTTP support (default)
npm start

# SSE-only server mode
npm run server:sse

# Traditional STDIO mode (for Claude Desktop)
npm run server:stdio
```

## 🔧 API Endpoints

The enhanced server exposes several REST endpoints:

- `GET /` - Web interface
- `GET /api/tools` - List all available tools
- `POST /api/call-tool` - Execute a tool via HTTP
- `GET /sse` - Server-Sent Events endpoint for real-time communication
- `POST /messages` - SSE message handler
- `GET /health` - Health check endpoint

## 🎯 Facebook Marketing API Tools

This server includes **58 pre-configured tools** for the Facebook Marketing API, organized into categories:

### Available Tool Categories:
- **Campaign Management**: Create, update, and retrieve campaign details
- **Ad Set Operations**: Manage ad sets with targeting and budgets
- **Creative Management**: Handle ad creatives and assets
- **Insights & Analytics**: Get performance data and reports
- **Account Management**: Manage ad accounts and permissions
- **Targeting**: Access targeting categories and audience data

### Example Tools:
- `get_campaign_insights` - Retrieve campaign performance data
- `create_campaign` - Create new advertising campaigns
- `get_ad_account_details` - Get detailed account information
- `update_ad_set` - Modify ad set configurations
- `get_targeting_categories` - Access available targeting options

## 🌐 Test the MCP Server with Postman

The MCP Server (`mcpServer.js`) exposes your automated API tools to MCP-compatible clients, such as Claude Desktop or the Postman Desktop Application. We recommend that you test the server with Postman first and then move on to using it with an LLM.

The Postman Desktop Application is the easiest way to run and test MCP servers. Testing the downloaded server first is optional but recommended.

**Step 1**: Download the latest Postman Desktop Application from [https://www.postman.com/downloads/](https://www.postman.com/downloads/).

**Step 2**: Read out the documentation article [here](https://learning.postman.com/docs/postman-ai-agent-builder/mcp-requests/create/) and see how to create an MCP request inside the Postman app.

**Step 3**: Set the type of the MCP request to `STDIO` and set the command to `node </absolute/path/to/mcpServer.js>`. If you have issues with using only `node` (e.g. an old version is used), supply an absolute path instead to a node version 18+. You can get the full path to node by running:

```sh
which node
```

To check the node version, run:

```sh
node --version
```

To get the absolute path to `mcpServer.js`, run:

```sh
realpath mcpServer.js
```

Use the node command followed by the full path to `mcpServer.js` as the command for your new Postman MCP Request. Then click the **Connect** button. You should see a list of tools that you selected before generating the server. You can test that each tool works here before connecting the MCP server to an LLM.

## 👩‍💻 Connect the MCP Server to Claude

You can connect your MCP server to any MCP client. Here we provide instructions for connecting it to Claude Desktop.

**Step 1**: Note the full path to node and the `mcpServer.js` from the previous step.

**Step 2**. Open Claude Desktop → **Settings** → **Developers** → **Edit Config** and add a new MCP server:

```json
{
  "mcpServers": {
    "<server_name>": {
      "command": "<absolute/path/to/node>",
      "args": ["<absolute/path/to/mcpServer.js>"]
    }
  }
}
```

Restart Claude Desktop to activate this change. Make sure the new MCP is turned on and has a green circle next to it. If so, you're ready to begin a chat session that can use the tools you've connected.

**Warning**: If you don't supply an absolute path to a `node` version that is v18+, Claude (and other MCP clients) may fall back to another `node` version on the system of a previous version. In this case, the `fetch` API won't be present and tool calls will not work. If that happens, you can a) install a newer version of node and point to it in the command, or b) import `node-fetch` into each tool as `fetch`, making sure to also add the `node-fetch` dependency to your package.json.

### Additional Options

#### 🐳 Docker Deployment (Production)

For production deployments, you can use Docker:

**1. Build Docker image**

```sh
docker build -t <your_server_name> .
```

**2. Claude Desktop Integration**

Add Docker server configuration to Claude Desktop (Settings → Developers → Edit Config):

```json
{
  "mcpServers": {
    "<your_server_name>": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "<your_server_name>"]
    }
  }
}
```

> Add your environment variables (API keys, etc.) inside the `.env` file.

The project comes bundled with the following minimal Docker setup:

```dockerfile
FROM node:22.12-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install

COPY . .

ENTRYPOINT ["node", "mcpServer.js"]
```

#### 🌐 Server-Sent Events (SSE)

To run the server with Server-Sent Events (SSE) support, use the `--sse` flag:

```sh
node mcpServer.js --sse
```

Or use the web interface which includes both SSE and HTTP streaming support:

```sh
npm start
```
## 🛠️ Additional CLI commands

#### List tools

List descriptions and parameters from all generated tools with:

```sh
node index.js tools
```

Example:

```
Available Tools:

Workspace: acme-workspace
  Collection: useful-api
    list_all_customers
      Description: Retrieve a list of useful things.
      Parameters:
        - magic: The required magic power
        - limit: Number of results returned
        [...additional parameters...]
```

## 🔧 API Endpoints

When running in web mode, the server exposes several endpoints:

- `GET /` - Web interface
- `GET /api/tools` - List available tools
- `POST /api/call-tool` - Execute a tool via HTTP
- `GET /sse` - Server-Sent Events endpoint
- `POST /messages` - SSE message handler
- `GET /health` - Health check endpoint

## 🎯 Features

### Web Interface Features
- **Modern UI**: Clean, responsive design with Facebook branding
- **Real-time Updates**: Live connection status and activity logging
- **Tool Management**: Browse and execute tools with parameter validation
- **Result Export**: Export execution results as JSON
- **Multiple Protocols**: Support for both SSE and HTTP streaming
- **Error Handling**: Comprehensive error reporting and user feedback

### Server Features
- **Multi-mode Operation**: STDIO, SSE, and HTTP support
- **Session Management**: Handle multiple concurrent connections
- **Tool Discovery**: Automatic detection of available tools
- **Health Monitoring**: Built-in health check endpoints
- **CORS Support**: Cross-origin resource sharing for web clients
## ➕ Adding New Tools

Extend your MCP server with more tools easily:

1. Visit [Postman MCP Generator](https://postman.com/explore/mcp-generator).
2. Pick new API request(s), generate a new MCP server, and download it.
3. Copy new generated tool(s) into your existing project's `tools/` folder.
4. Update your `tools/paths.js` file to include new tool references.

## 💬 Questions & Support

Visit the [Postman MCP Generator](https://postman.com/explore/mcp-generator) page for updates and new capabilities.

Join the `#mcp-lab` channel in the [Postman Discord](https://discord.gg/HQJWM8YF) to share what you've built and get help.