Postmancer

What hijaz/postmancer MCP server does

The hijaz/postmancer MCP server gives AI assistants an MCP interface for working with REST APIs. It can send a request directly to any URL, or execute a request saved in a named collection. Collections provide a way to organize reusable API calls instead of rebuilding each request during a conversation.

The server also supports request templates that use environment variables. An assistant can list existing variables, set new values, and reuse those values when working with saved requests. The README describes support for Basic authentication, Bearer tokens, API keys, and OAuth2. It also lists request and response history and testing among the available capabilities.

How it works

An MCP-compatible client starts Postmancer as a local process and communicates with it through the server's exposed tools. The direct request tool accepts a URL and sends the HTTP request. Collection-oriented tools let the assistant inspect available collections, enumerate the requests in one collection, save a new request, and run a saved request later.

Collection data is stored under the configured collections directory. If no directory is specified, the default location is ~/.postmancer. Environment variables are available for request templating, and variables marked as secrets can be encrypted. Credentials and tokens use a separate encryption setting. The server generates random encryption keys when the relevant settings are absent, although the documentation recommends explicitly configuring keys in production.

This workflow suits API exploration, repeatable endpoint checks, and assistants that need to retain request definitions across sessions. It does not describe a hosted API or a remote service; the supplied setup runs the MCP server locally through npm or Docker.

Setup and configuration

The hijaz/postmancer MCP server can be installed globally with npm using npm install -g postmancer, or started directly with npx postmancer. The documented non-interactive Claude Desktop configuration uses npx with -y and the postmancer package. Claude Desktop configuration files are located at %USERPROFILE%\.claude\claude_desktop_config.json on Windows and ~/.claude/claude_desktop_config.json on macOS and Linux.

Docker is also supported. The README shows the server running interactively with docker run -i --rm postmancer, optionally mounting a local collections directory at /data/collections. The example uses a placeholder host path, which must be replaced when configuring a real mount.

Configuration options include COLLECTIONS_PATH for collection storage and LOG_LEVEL for debug, info, warn, or error logging. POSTMANCER_ENCRYPTION_KEY protects credentials and tokens, while ENCRYPTION_KEY protects secret environment variables. Both logging and storage settings have defaults; the encryption settings also have fallback behavior when omitted.

Tools and capabilities

• Send HTTP requests to any URL with http_request.
• List saved collections with list_collections.
• Inspect requests inside a collection with list_requests.
• Store a request with save_request.
• Execute a saved request with request_from_collection.
• Set template variables with set_environment_variable.
• Read available variables with get_environment_variables.