emcee

You can install emcee using several methods depending on your platform and preference:

Homebrew (macOS)

brew install mattt/tap/emcee

Installer Script (Linux and macOS)

For Linux (x86-64/i386/arm64) and macOS (Intel/Apple Silicon):

fish

sh (curl -fsSL https://get.emcee.sh | psub)

bash, zsh

sh <(curl -fsSL https://get.emcee.sh)

Docker

docker run -it ghcr.io/mattt/emcee

Build From Source

Requires Go 1.24 or later:

git clone https://github.com/mattt/emcee.git
cd emcee
go build -o emcee cmd/emcee/main.go

To use emcee as an MCP server in Claude Desktop, you must edit your claude_desktop_config.json file.

1. Open Claude Desktop Settings (⌘,).
2. Select "Developer" in the sidebar.
3. Click "Edit Config".

Alternatively, open the file directly via terminal:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add an entry to the mcpServers object. For example, to add the weather.gov API:

{
  "mcpServers": {
    "weather": {
      "command": "emcee",
      "args": ["https://api.weather.gov/openapi.json"]
    }
  }
}

Restart Claude Desktop after saving. You should see a tool icon (e.g., 🔨) in the chat box indicating available tools.

The emcee CLI tool creates a Model Context Protocol (MCP) server using a stdio transport based on a provided OpenAPI specification. It processes JSON-RPC requests from stdin and returns responses to stdout.

To use emcee, you must provide exactly one argument representing the path or URL to your OpenAPI specification:

• Local file path: e.g., ./openapi.json
• HTTP(S) URL: e.g., https://api.example.com/openapi.json
• Stdin: Use - to read the specification from standard input.

Note on Stdin: If you use - to read the spec from stdin, emcee will redirect its internal MCP communication to read from /dev/tty to ensure it can still receive JSON-RPC requests via the standard input stream.

emcee ./path/to/openapi.json
emcee https://api.example.com/openapi.json
echo '{"openapi": "3.0.0"}' | emcee -

If emcee is not behaving as expected in your MCP client, use the @modelcontextprotocol/inspector to test the server in isolation.

Run the following command:

npx @modelcontextprotocol/inspector emcee https://api.weather.gov/openapi.json

This will start the inspector at http://localhost:5173. Open that URL in your browser to interact with the emcee server and inspect requests/responses.

You can pipe transformed OpenAPI specifications into emcee using standard Unix utilities. This allows you to filter which endpoints are exposed as MCP tools.

Example: Using jq to expose only a specific endpoint If you only want to expose the /points/{point} tool from a weather.gov specification:

cat path/to/openapi.json | \
  jq 'if .paths then .paths |= with_entries(select(.key == "/points/{point}")) else . end' | \
  emcee

When the OpenAPI specification requires authentication to access the underlying API, you can provide credentials via the following mutually exclusive flags. All flags support 1Password secret references (e.g., op://vault/item/field).

To use 1Password references:

• The op CLI must be installed and in your PATH.
• You must be signed in to 1Password.

Authentication Flags:

• --bearer-auth <token>: Sets the Authorization: Bearer <token> header.
• --basic-auth <user:pass>: Sets the Authorization: Basic <base64-encoded-credentials> header. You can provide either a user:pass string or a pre-encoded base64 string.
• --raw-auth <value>: Sets the Authorization: <value> header for custom formats.

emcee ./openapi.json --bearer-auth op://private/api-key
emcee ./openapi.json --basic-auth admin:password123

By default, emcee generates annotations for the tools derived from the OpenAPI specification. Use the --no-annotations flag to disable this behavior.

emcee ./openapi.json --no-annotations

Control the verbosity of emcee logs (which are sent to stderr to avoid interfering with the stdout JSON-RPC transport):

• --verbose (or -v): Enable debug level logging.
• --silent (or -s): Disable all logging.

Note: --verbose and --silent are mutually exclusive.

emcee ./openapi.json --verbose
emcee ./openapi.json --silent

You can tune how emcee interacts with the target API using the following flags:

• --retries <int>: Maximum number of retries for failed requests (default: 3).
• --timeout <duration>: HTTP request timeout (e.g., 30s, 1m) (default: 60s).
• --rps <int>: Maximum requests per second (rate limiting). Use 0 for no limit (default: 0).
• --insecure: Allow insecure TLS connections by skipping certificate verification.

emcee ./openapi.json --retries 5 --timeout 30s --rps 10 --insecure