Repository files navigation

emcee is a tool that provides aModel Context Protocol (MCP) serverfor any web application with anOpenAPI specification.You can use emcee to connectClaude Desktop andother appsto external tools and data services,similar toChatGPT plugins.

If you're on macOS and haveHomebrew installed,you can get up-and-running quickly.

# Install emceebrew install loopwork-ai/tap/emcee

Make sure you haveClaude Desktop installed.

To configure Claude Desktop for use with emcee:

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

The configuration file should be located in the Application Support directory.You can also open it directly in VSCode using:

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

Add the following configuration to add the weather.gov MCP server:

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

After saving the file, quit and re-open Claude.You should now see🔨57 in the bottom right corner of your chat box.Click on that to see a list of all the tools made available to Claude through MCP.

Start a new chat and ask it about the weather where you are.

What's the weather in Portland, OR?

Claude will consult the tools made available to it through MCPand request to use one if deemed to be suitable for answering your question.You can review this request and either approve or deny it.

If you allow, Claude will communicate with the MCPand use the result to inform its response.

MCP provides a standardized way to connect AI models to tools and data sources.It's still early days, but there are already a variety ofavailable serversfor connecting to browsers, developer tools, and other systems.

We think emcee is a convenient way to connect to servicesthat don't have an existing MCP server implementation —especially for services you're building yourself.Got a web app with an OpenAPI spec?You might be surprised how far you can getwithout a dashboard or client library.

Use theinstaller script to download and install apre-built release of emcee for your platform(Linux x86-64/i386/arm64 and macOS Intel/Apple Silicon).

#fishsh (curl -fsSL https://get.emcee.sh | psub)#bash, zshsh <(curl -fsSL https://get.emcee.sh)

Install emcee usingHomebrew fromLoopwork's tap.

brew install loopwork-ai/tap/emcee

PrebuiltDocker images with emcee are available.

docker run -it ghcr.io/loopwork-ai/emcee

Requiresgo 1.24 or later.

git clone https://github.com/loopwork-ai/emcee.gitcd emceego build -o emcee cmd/emcee/main.go

Once built, you can run in place (./emcee)or move it somewhere in yourPATH, like/usr/local/bin.

Usage:  emcee [spec-path-or-url] [flags]Flags:      --basic-auth string    Basic auth value (either user:pass or base64 encoded, will be prefixed with 'Basic ')      --bearer-auth string   Bearer token value (will be prefixed with 'Bearer ')  -h, --help                 help for emcee      --raw-auth string      Raw value for Authorization header      --retries int          Maximum number of retries for failed requests (default 3)  -r, --rps int              Maximum requests per second (0 for no limit)  -s, --silent               Disable all logging      --timeout duration     HTTP request timeout (default 1m0s)  -v, --verbose              Enable debug level logging to stderr      --version              version for emcee

emcee implementsStandard Input/Output (stdio) transport for MCP,which usesJSON-RPC 2.0 as its wire format.

When you run emcee from the command-line,it starts a program that listens on stdin,outputs to stdout,and logs to stderr.

For APIs that require authentication,emcee supports several authentication methods:

These authentication values can be provided directlyor as1Password secret references.

When using 1Password references:

• Use the formatop://vault/item/field(e.g.--bearer-auth="op://Shared/X/credential")
• Ensure the 1Password CLI (op) is installed and available in yourPATH
• Sign in to 1Password before running emcee or launching Claude Desktop

#Install opbrew install 1password-cli#Signin 1Password CLIop signin

{"mcpServers": {"twitter": {"command":"emcee","args": ["--bearer-auth=op://shared/x/credential","https://api.twitter.com/2/openapi.json"      ]    }  }}

You can transform OpenAPI specifications before passing them to emcee using standard Unix utilities. This is useful for:

• Selecting specific endpoints to expose as toolswithjq oryq
• Modifying descriptions or parameterswithOpenAPI Overlays
• Combining multiple specificationswithRedocly

For example,you can usejq to include only thepoint tool fromweather.gov.

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

You can interact directly with the provided MCP serverby sending JSON-RPC requests.

{"jsonrpc":"2.0","method":"tools/list","params": {},"id":1}

{"jsonrpc":"2.0","result":{"tools":[// ...{"name":"tafs","description":"Returns Terminal Aerodrome Forecasts for the specified airport station.","inputSchema":{"type":"object","properties":{"stationId":{"description":"Observation station ID","type":"string"}},"required":["stationId"]}},// ...]},"id":1}

{"jsonrpc":"2.0","method":"tools/call","params": {"name":"taf","arguments": {"stationId":"KPDX" }},"id":1}

{"jsonrpc":"2.0","content":[{"type":"text","text":/* Weather forecast in GeoJSON format */,"annotations":{"audience":["assistant"]}}]  "id":1}

TheMCP Inspector is a tool for testing and debugging MCP servers.If Claude and/or emcee aren't working as expected,the inspector can help you understand what's happening.

npx @modelcontextprotocol/inspector emcee https://api.weather.gov/openapi.json#🔍 MCP Inspector is up and running at http://localhost:5173 🚀

open http://localhost:5173

emcee is licensed under the Apache License, Version 2.0.