Emcee

emcee

emcee es una herramienta que proporciona un servidor Model Context Protocol (MCP) para cualquier aplicación web con una especificación OpenAPI. Puedes usar emcee para conectar Claude Desktop y otras aplicaciones a herramientas externas y servicios de datos, similar a los plugins de ChatGPT.

Inicio rápido

Si estás en macOS y tienes Homebrew instalado, puedes ponerte en marcha rápidamente.

# Install emcee
brew install mattt/tap/emcee

Asegúrate de tener Claude Desktop instalado.

Para configurar Claude Desktop para usar con emcee:

1. Abre la configuración de Claude Desktop (⌘,)
2. Selecciona la sección "Developer" en la barra lateral
3. Haz clic en "Edit Config" para abrir el archivo de configuración

El archivo de configuración debería estar ubicado en el directorio Application Support. También puedes abrirlo directamente en VSCode usando:

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

Agrega la siguiente configuración para añadir el servidor MCP de weather.gov:

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

Después de guardar el archivo, sal y vuelve a abrir Claude. Ahora deberías ver 🔨57 en la esquina inferior derecha de tu cuadro de chat. Haz clic en eso para ver una lista de todas las herramientas disponibles para Claude a través de MCP.

Inicia un nuevo chat y pregúntale sobre el clima donde estás.

¿Cómo está el clima en Portland, OR?

Claude consultará las herramientas que se le han puesto a disposición a través de MCP y solicitará usar una si considera que es adecuada para responder tu pregunta. Puedes revisar esta solicitud y aprobarla o denegarla.

Si lo permites, Claude se comunicará con el MCP y usará el resultado para informar su respuesta.

¿Por qué usar emcee?

MCP proporciona una forma estandarizada de conectar modelos de IA a herramientas y fuentes de datos. Aún es temprano, pero ya hay una variedad de servidores disponibles para conectarse a navegadores, herramientas de desarrollo y otros sistemas.

Creemos que emcee es una forma conveniente de conectarse a servicios que no tienen una implementación de servidor MCP existente — especialmente para servicios que estás construyendo tú mismo. ¿Tienes una aplicación web con una especificación OpenAPI? Podrías sorprenderte de lo lejos que puedes llegar sin un panel de control o una biblioteca de cliente.

Instalación

Script de instalación

Usa el script de instalación para descargar e instalar una versión precompilada de emcee para tu plataforma (Linux x86-64/i386/arm64 y macOS Intel/Apple Silicon).

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

# bash, zsh
sh <(curl -fsSL https://get.emcee.sh)

Homebrew

Instala emcee usando Homebrew.

brew install mattt/tap/emcee

Docker

Hay imágenes de Docker precompiladas con emcee disponibles.

docker run -it ghcr.io/mattt/emcee

Compilar desde el código fuente

Requiere go 1.24 o posterior.

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

Una vez compilado, puedes ejecutarlo en el lugar (./emcee) o moverlo a algún lugar en tu PATH, como /usr/local/bin.

Uso

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 implementa el transporte Standard Input/Output (stdio) para MCP, que utiliza JSON-RPC 2.0 como su formato de transmisión.

Cuando ejecutas emcee desde la línea de comandos, inicia un programa que escucha en stdin, escribe en stdout y registra en stderr.

Autenticación

Para APIs que requieren autenticación, emcee admite varios métodos de autenticación:

Estos valores de autenticación se pueden proporcionar directamente o como referencias secretas de 1Password.

Al usar referencias de 1Password:

• Usa el formato op://vault/item/field (por ejemplo, --bearer-auth="op://Shared/X/credential")
• Asegúrate de que la CLI de 1Password (op) esté instalada y disponible en tu PATH
• Inicia sesión en 1Password antes de ejecutar emcee o lanzar Claude Desktop

# Install op
brew install 1password-cli

# Sign in 1Password CLI
op signin

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

[!IMPORTANT]
emcee no usa credenciales de autenticación al descargar especificaciones OpenAPI desde URLs proporcionadas como argumentos de comando. Si tu especificación OpenAPI requiere autenticación para acceder, primero descárgala a un archivo local usando tu cliente HTTP preferido, luego proporciona la ruta del archivo local a emcee.

Transformando especificaciones OpenAPI

Puedes transformar especificaciones OpenAPI antes de pasarlas a emcee usando utilidades estándar de Unix. Esto es útil para:

• Seleccionar endpoints específicos para exponer como herramientas con jq o yq
• Modificar descripciones o parámetros con OpenAPI Overlays
• Combinar múltiples especificaciones con Redocly

Por ejemplo, puedes usar jq para incluir solo la herramienta point de weather.gov.

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

HTTP QUERY

emcee admite el método HTTP QUERY definido por RFC 10008. Las especificaciones OpenAPI 3.2 pueden usar la operación nativa query de Path Item; las especificaciones OpenAPI 3.x más antiguas pueden usar x-query como extensión de compatibilidad. El valor se analiza como un Objeto de Operación OpenAPI estándar, se registra como herramienta MCP y se anota como de solo lectura e idempotente.

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

Puedes interactuar directamente con el servidor MCP proporcionado enviando solicitudes JSON-RPC.

[!NOTE] emcee solo proporciona capacidades de herramientas MCP. Otras características como recursos, indicaciones y muestreo aún no son compatibles.

Listar herramientas

{ "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
}

Llamar herramienta

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

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

Depuración

El Inspector MCP es una herramienta para probar y depurar servidores MCP. Si Claude y/o emcee no funcionan como se espera, el inspector puede ayudarte a entender lo que está sucediendo.

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

open http://localhost:5173

Licencia

Este proyecto está disponible bajo la licencia MIT. Consulta el archivo LICENSE para más información.