emcee

emcee is a tool that provides a [Model Context Protocol (MCP)][mcp] server

for any web application with an [OpenAPI][openapi] specification.

You can use emcee to connect [Claude Desktop][claude] and [other apps][mcp-clients]

to external tools and data services,

similar to [ChatGPT plugins][chatgpt-plugins].

Quickstart

If you're on macOS and have [Homebrew][homebrew] installed,

you can get up-and-running quickly.

# Install emcee
brew install mattt/tap/emcee

Make sure you have Claude 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 MCP

and 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 MCP

and use the result to inform its response.

Why use emcee?

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 of [available servers][mcp-servers]

for connecting to browsers, developer tools, and other systems.

We think emcee is a convenient way to connect to services

that 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 get

without a dashboard or client library.

Installation

Installer Script

Use the [installer script][installer] to download and install a

[pre-built release][releases] of emcee for your platform

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

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

# bash, zsh
sh 

> [!IMPORTANT]  
> emcee doesn't use auth credentials when downloading
> OpenAPI specifications from URLs provided as command arguments.
> If your OpenAPI specification requires authentication to access,
> first download it to a local file using your preferred HTTP client,
> then provide the local file path to emcee.

### Transforming OpenAPI Specifications

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

- Selecting specific endpoints to expose as tools
  with [jq][jq] or [yq][yq]
- Modifying descriptions or parameters
  with [OpenAPI Overlays][openapi-overlays]
- Combining multiple specifications
  with [Redocly][redocly-cli]

For example,
you can use `jq` to include only the `point` tool from `weather.gov`.

emcee

### HTTP QUERY

emcee supports the HTTP `QUERY` method defined by [RFC 10008][rfc-query].
OpenAPI 3.2 specifications can use the native `query` Path Item operation;
older OpenAPI 3.x specifications can use `x-query` as a compatibility extension.
The value is parsed as a standard OpenAPI Operation Object,
registered as an MCP tool,
and annotated as read-only and idempotent.

paths:

/search:

query:

operationId: search

summary: Search records

requestBody:

content:

application/json:

schema:

type: object

properties:

q:

type: string

responses:

"200":

description: OK

### JSON-RPC

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

> [!NOTE]
> emcee provides only MCP tool capabilities.
> Other features like resources, prompts, and sampling aren't yet supported.

#### List Tools

Request

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

Response

{

"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

}

#### Call Tool

Request

{

"jsonrpc": "2.0",

"method": "tools/call",

"params": { "name": "taf", "arguments": { "stationId": "KPDX" } },

"id": 1

}

Response

{

"jsonrpc": "2.0",

"result": {

"content": [

{

"type": "text",

"text": "/* Weather forecast in GeoJSON format */"

}

]

},

"id": 1

}

## Debugging

The [MCP Inspector][mcp-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 🚀

// Code block

open http://localhost:5173

## License

This project is available under the MIT license.
See the LICENSE file for more info.

[chatgpt-plugins]: https://openai.com/index/chatgpt-plugins/
[claude]: https://claude.ai/download
[docker-images]: https://github.com/mattt/emcee/pkgs/container/emcee
[golang]: https://go.dev
[homebrew]: https://brew.sh
[installer]: https://github.com/mattt/emcee/blob/main/tools/install.sh
[jq]: https://github.com/jqlang/jq
[mcp]: https://modelcontextprotocol.io/
[mcp-clients]: https://modelcontextprotocol.info/docs/clients/
[mcp-inspector]: https://github.com/modelcontextprotocol/inspector
[mcp-servers]: https://modelcontextprotocol.io/examples
[op]: https://developer.1password.com/docs/cli/get-started/
[openapi]: https://openapi.org
[openapi-overlays]: https://www.openapis.org/blog/2024/10/22/announcing-overlay-specification
[redocly-cli]: https://redocly.com/docs/cli/commands
[releases]: https://github.com/mattt/emcee/releases
[rfc-query]: https://datatracker.ietf.org/doc/rfc10008/
[secret-reference-syntax]: https://developer.1password.com/docs/cli/secret-reference-syntax/
[yq]: https://github.com/mikefarah/yq