HttpProxyMcp (sailro/httpproxymcp)

HttpProxyMcp

https://github.com/sailro/httpproxymcp
Admin
HttpProxyMcp is an HTTP/HTTPS MITM proxy with full traffic capture that exposes network analysis...

Tokens:10,898
Snippets:60
Trust Score:9.4
Update:1 week ago
Show doc for...
Context Summary (auto-generated)
Raw
# HttpProxyMcp

HttpProxyMcp is an HTTP/HTTPS Man-in-the-Middle (MITM) proxy with full traffic capture, exposed as a Model Context Protocol (MCP) server. It enables LLMs to inspect, filter, and analyze network traffic through natural language commands. Built with .NET 10, the proxy uses Titanium.Web.Proxy for HTTPS interception with dynamic certificate generation, stores all captured data in SQLite, and auto-configures the Windows system proxy for seamless browser integration.

The server communicates via stdio using the MCP protocol and exposes 14 tools organized into three categories: proxy control (start/stop/status), session management (create/list/activate/close/delete sessions), and traffic analysis (list/filter/search/statistics/export). All captured traffic—including requests, responses, headers, bodies, and timing information—is persisted to SQLite with WAL mode for concurrent access. The system supports HAR 1.2 export for compatibility with browser DevTools and other network analysis tools.

## MCP Configuration

Configure MCP client to launch HttpProxyMcp server.

Add the server configuration to your MCP client's config file. The server communicates over stdio and requires .NET 10 SDK to be installed.

```json
{
  "mcpServers": {
    "httpproxymcp": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/path/to/src/HttpProxyMcp.McpServer/HttpProxyMcp.McpServer.csproj"
      ]
    }
  }
}
```

## StartProxy

Start the HTTP/HTTPS MITM proxy on the specified port with optional SSL interception and system proxy configuration. When `setSystemProxy` is true (default), the proxy automatically configures Windows Internet Settings—no manual browser setup needed.

```javascript
// MCP Tool: StartProxy
// Parameters:
{
  "port": 8080,           // Port to listen on (default: 8080)
  "enableSsl": true,      // Enable HTTPS MITM interception (default: true)
  "setSystemProxy": true  // Auto-configure Windows system proxy (default: true)
}

// Example response:
"Proxy started on port 8080 (SSL interception: True). System proxy configured."

// Error response (port in use):
"Failed to start proxy on port 8080: Only one usage of each socket address is normally permitted."
```

## StopProxy

Stop the running proxy and restore original Windows system proxy settings. The proxy registers multiple cleanup handlers (ProcessExit, CancelKeyPress, Dispose) to ensure settings are restored even on unexpected termination.

```javascript
// MCP Tool: StopProxy
// No parameters required

// Example response (proxy running):
"Proxy stopped."

// Example response (proxy not running):
"Proxy is not running."
```

## GetProxyStatus

Check the current state of the proxy including whether it's running, the port, and SSL interception status.

```javascript
// MCP Tool: GetProxyStatus
// No parameters required

// Example response (running):
"Proxy is running on port 8080 (SSL: True)."

// Example response (stopped):
"Proxy is not running."
```

## CreateSession

Create a new capture session to logically group related traffic. Sessions allow you to organize captures by workflow (e.g., "login-flow", "api-testing", "debugging-checkout").

```javascript
// MCP Tool: CreateSession
// Parameters:
{
  "name": "login-flow"  // Session name (required)
}

// Example response:
"Created session \"login-flow\" (3fa85f64-5717-4562-b3fc-2c963f66afa6)."
```

## ListSessions

List all capture sessions with their entry counts, status, and creation timestamps.

```javascript
// MCP Tool: ListSessions
// No parameters required

// Example response:
// [3fa85f64-5717-4562-b3fc-2c963f66afa6] "login-flow" — 42 entries (active) created 6/15/2024 2:30 PM
// [7c9e6679-7425-40de-944b-e07fc1f90ae7] "api-testing" — 156 entries (closed 6/15/2024 3:45 PM) created 6/15/2024 1:00 PM

// Example response (no sessions):
"No sessions found."
```

## SetActiveSession

Set which session captures new traffic. Only one session can be active at a time—all new traffic is automatically assigned to the active session.

```javascript
// MCP Tool: SetActiveSession
// Parameters:
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  // Session GUID (required)
}

// Example response:
"Active session set to 3fa85f64-5717-4562-b3fc-2c963f66afa6."
```

## CloseSession

Close a capture session to stop capturing new traffic to it. Closed sessions retain their data and can still be queried.

```javascript
// MCP Tool: CloseSession
// Parameters:
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  // Session GUID (required)
}

// Example response:
"Session 3fa85f64-5717-4562-b3fc-2c963f66afa6 closed."
```

## DeleteSession

Delete a capture session and all its associated traffic data. This action is permanent—the session and all traffic entries are removed from the database via foreign key cascade.

```javascript
// MCP Tool: DeleteSession
// Parameters:
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  // Session GUID (required)
}

// Example response:
"Session 3fa85f64-5717-4562-b3fc-2c963f66afa6 deleted."
```

## ListTraffic

List captured traffic entries with flexible filtering options. Supports filtering by hostname, HTTP method, URL pattern, status code, with pagination via limit and offset.

```javascript
// MCP Tool: ListTraffic
// Parameters:
{
  "hostname": "api.github.com",  // Filter by hostname (optional)
  "method": "POST",              // Filter by HTTP method (optional)
  "urlPattern": "/v1/users",     // Filter by URL pattern (optional)
  "statusCode": 200,             // Filter by exact status code (optional)
  "limit": 50,                   // Maximum results (default: 50)
  "offset": 0                    // Pagination offset (default: 0)
}

// Example response:
// Showing 3 of 3 entries:
// [1] GET https://api.github.com/user → 200 (145ms)
// [2] POST https://api.github.com/repos → 201 (312ms)
// [3] GET https://api.github.com/repos/owner/repo → 404 (89ms)

// Filter POST requests with 4xx errors:
{
  "method": "POST",
  "statusCode": 400
}

// Response:
// Showing 1 of 1 entries:
// [15] POST https://api.example.com/login → 400 (234ms)
```

## GetTrafficEntry

Get full details of a captured traffic entry by ID, including complete request/response headers, bodies, timing, and metadata.

```javascript
// MCP Tool: GetTrafficEntry
// Parameters:
{
  "id": 42  // Traffic entry ID (required)
}

// Example response:
// === Traffic Entry 42 ===
// Started: 2024-06-15T14:32:45.1234567+00:00
// Duration: 234ms
//
// --- Request ---
// POST https://api.example.com/auth/login
// Headers:
//   Content-Type: application/json
//   User-Agent: Mozilla/5.0
//   Accept: application/json
// Body:
// {"username":"user@example.com","password":"***"}
//
// --- Response ---
// 200 OK
// Headers:
//   Content-Type: application/json
//   Set-Cookie: session=abc123; HttpOnly; Secure
// Body:
// {"token":"eyJhbGciOiJIUzI1NiIs...","expires_in":3600}

// Entry not found:
"Traffic entry 999 not found."
```

## SearchBodies

Search through request and response bodies for specific text. Useful for finding API calls containing specific data, error messages, or sensitive information.

```javascript
// MCP Tool: SearchBodies
// Parameters:
{
  "searchText": "Authorization",  // Text to search for (required)
  "limit": 50                     // Maximum results (default: 50)
}

// Example response:
// Found 5 entries matching "Authorization":
// [12] GET https://api.github.com/user → 200
// [15] POST https://api.stripe.com/v1/charges → 201
// [23] GET https://api.example.com/protected → 401
// [31] DELETE https://api.example.com/users/123 → 204
// [45] PUT https://api.example.com/settings → 200

// Search for error responses:
{
  "searchText": "\"error\":"
}

// Response:
// Found 2 entries matching "\"error\":":
// [8] POST https://api.example.com/login → 401
// [19] POST https://api.example.com/payment → 402
```

## GetStatistics

Get traffic statistics aggregated by HTTP method, status code, and hostname. Optionally scope to a specific session.

```javascript
// MCP Tool: GetStatistics
// Parameters:
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  // Optional session filter
}

// Example response:
// Total requests: 156
// Request bytes: 45,678
// Response bytes: 1,234,567
// Avg duration: 187ms
// By method: GET=98, POST=42, PUT=12, DELETE=4
// By status: 200=120, 201=25, 400=5, 401=3, 404=2, 500=1
// Top hosts: api.github.com=45, api.stripe.com=32, api.example.com=79

// Without sessionId returns statistics for all captured traffic
```

## ClearTraffic

Delete captured traffic data. Can clear all traffic or scope to a specific session.

```javascript
// MCP Tool: ClearTraffic
// Parameters:
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  // Optional session filter
}

// Example response (with sessionId):
"Cleared traffic for session 3fa85f64-5717-4562-b3fc-2c963f66afa6."

// Example response (without sessionId):
"Cleared all captured traffic."
```

## ExportHar

Export a capture session to HAR 1.2 format for analysis in browser DevTools, Charles, Fiddler, or other network analysis tools. The export includes granular timing data, server IP addresses, cookies, and full request/response bodies.

```javascript
// MCP Tool: ExportHar
// Parameters:
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // Session GUID (required)
  "filePath": "/path/to/output/session.har"             // Output file path (required)
}

// Example response:
"Exported 156 entries to /path/to/output/session.har"

// Error response (empty session):
"No traffic entries found for session 3fa85f64-5717-4562-b3fc-2c963f66afa6."

// HAR output structure:
{
  "log": {
    "version": "1.2",
    "creator": { "name": "HttpProxyMcp", "version": "1.0" },
    "entries": [
      {
        "startedDateTime": "2024-06-15T14:32:45.123Z",
        "time": 234.5,
        "serverIPAddress": "192.168.1.100",
        "request": {
          "method": "POST",
          "url": "https://api.example.com/login",
          "httpVersion": "HTTP/2.0",
          "headers": [...],
          "cookies": [...],
          "queryString": [...],
          "postData": { "mimeType": "application/json", "text": "{...}" }
        },
        "response": {
          "status": 200,
          "statusText": "OK",
          "httpVersion": "HTTP/2.0",
          "headers": [...],
          "cookies": [...],
          "content": { "size": 1234, "mimeType": "application/json", "text": "{...}" },
          "redirectURL": ""
        },
        "timings": { "send": 1.5, "wait": 180.2, "receive": 52.8 }
      }
    ]
  }
}
```

## ProxyConfiguration

Configure the proxy engine with custom settings including port, SSL options, certificate paths, and hostname exclusions.

```csharp
// ProxyConfiguration model
var config = new ProxyConfiguration
{
    Port = 8080,                          // Listen port (default: 8080)
    EnableSsl = true,                     // HTTPS MITM interception (default: true)
    SetSystemProxy = true,                // Auto-configure Windows proxy (default: true)
    RootCertificatePath = null,           // Custom root CA PFX path (optional)
    RootCertificatePassword = null,       // PFX password (optional)
    MaxBodyCaptureBytes = 10 * 1024 * 1024,  // Max body size: 10MB (default)
    ExcludedHostnames = new List<string>  // Hostnames to pass through without MITM
    {
        "localhost",
        "*.internal.company.com"
    }
};

// Start proxy with custom configuration via MCP:
{
  "port": 9090,
  "enableSsl": true,
  "setSystemProxy": false
}
```

## TrafficFilter

Filter captured traffic using flexible query criteria for targeted analysis.

```csharp
// TrafficFilter model - used internally by ListTraffic
var filter = new TrafficFilter
{
    SessionId = Guid.Parse("..."),     // Filter by session
    Hostname = "api.github.com",       // Exact hostname match
    UrlPattern = "/v1/",               // URL contains pattern
    Method = "POST",                   // HTTP method
    StatusCode = 200,                  // Exact status code
    MinStatusCode = 400,               // Status code range (min)
    MaxStatusCode = 499,               // Status code range (max)
    After = DateTimeOffset.Now.AddHours(-1),   // Time range start
    Before = DateTimeOffset.Now,               // Time range end
    ContentType = "application/json",  // Response content type
    BodySearchText = "error",          // Search in bodies
    Offset = 0,                        // Pagination offset
    Limit = 50                         // Results limit
};
```

## Summary

HttpProxyMcp serves as a powerful network debugging and analysis tool for developers working with LLMs. Primary use cases include debugging API integrations by capturing and inspecting HTTP/HTTPS traffic, analyzing authentication flows and session management, searching for sensitive data in request/response bodies, monitoring third-party API calls, and exporting traffic sessions to HAR format for sharing or further analysis in browser DevTools.

Integration patterns typically involve starting with an MCP client configuration, then using natural language prompts to control the proxy. A typical workflow involves creating a named session, starting the proxy with system proxy auto-configuration, performing the actions you want to capture (browsing, API calls), then querying and analyzing the traffic using filters, searches, and statistics. The HAR export enables seamless handoff to other tools while the SQLite persistence ensures captured traffic survives restarts and can be queried across sessions.