{"id":24614109,"url":"https://github.com/loopwork-ai/emcee","last_synced_at":"2025-04-09T05:12:35.235Z","repository":{"id":273938367,"uuid":"917778332","full_name":"loopwork-ai/emcee","owner":"loopwork-ai","description":"Connect agents to APIs 🫳🎤💥","archived":false,"fork":false,"pushed_at":"2025-03-29T11:44:13.000Z","size":153,"stargazers_count":188,"open_issues_count":1,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T04:05:37.317Z","etag":null,"topics":["agents","modelcontextprotocol","openapi"],"latest_commit_sha":null,"homepage":"https://emcee.sh","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loopwork-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-16T16:20:26.000Z","updated_at":"2025-04-01T20:22:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"4943f4b5-de84-4d4c-b2f8-00ad564d44a9","html_url":"https://github.com/loopwork-ai/emcee","commit_stats":null,"previous_names":["loopwork-ai/emcee"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2Femcee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2Femcee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2Femcee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2Femcee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loopwork-ai","download_url":"https://codeload.github.com/loopwork-ai/emcee/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980844,"owners_count":21027808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","modelcontextprotocol","openapi"],"created_at":"2025-01-24T21:15:04.693Z","updated_at":"2025-04-09T05:12:35.207Z","avatar_url":"https://github.com/loopwork-ai.png","language":"Go","readme":"![emcee flow diagram](https://github.com/user-attachments/assets/bcac98a5-497f-4b34-9e8d-d4bc08852ea1)\n\n# emcee\n\n**emcee** is a tool that provides a [Model Context Protocol (MCP)][mcp] server\nfor any web application with an [OpenAPI][openapi] specification.\nYou can use emcee to connect [Claude Desktop][claude] and [other apps][mcp-clients]\nto external tools and data services,\nsimilar to [ChatGPT plugins][chatgpt-plugins].\n\n## Quickstart\n\nIf you're on macOS and have [Homebrew][homebrew] installed,\nyou can get up-and-running quickly.\n\n```bash\n# Install emcee\nbrew install loopwork-ai/tap/emcee\n```\n\nMake sure you have [Claude Desktop](https://claude.ai/download) installed.\n\nTo configure Claude Desktop for use with emcee:\n\n1. Open Claude Desktop Settings (\u003ckbd\u003e⌘\u003c/kbd\u003e\u003ckbd\u003e,\u003c/kbd\u003e)\n2. Select the \"Developer\" section in the sidebar\n3. Click \"Edit Config\" to open the configuration file\n\n![Claude Desktop settings Edit Config button](https://github.com/user-attachments/assets/761c6de5-62c2-4c53-83e6-54362040acd5)\n\nThe configuration file should be located in the Application Support directory.\nYou can also open it directly in VSCode using:\n\n```console\ncode ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\nAdd the following configuration to add the weather.gov MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"weather\": {\n      \"command\": \"emcee\",\n      \"args\": [\n        \"https://api.weather.gov/openapi.json\"\n      ]\n    }\n  }\n}\n```\n\nAfter saving the file, quit and re-open Claude.\nYou should now see \u003ckbd\u003e🔨57\u003c/kbd\u003e in the bottom right corner of your chat box.\nClick on that to see a list of all the tools made available to Claude through MCP.\n\nStart a new chat and ask it about the weather where you are.\n\n\u003e What's the weather in Portland, OR?\n\nClaude will consult the tools made available to it through MCP\nand request to use one if deemed to be suitable for answering your question.\nYou can review this request and either approve or deny it.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/394ac476-17c2-4a29-aaff-9537d42b289b\" alt=\"Allow tool from weather MCP dialog\" width=\"460\"\u003e\n\nIf you allow, Claude will communicate with the MCP\nand use the result to inform its response.\n\n![Claude response with MCP tool use](https://github.com/user-attachments/assets/d5b63002-1ed3-4b03-bc71-8357427bb06b)\n\n---\n\n\u003e [!TIP]\n\u003e Building agents? Want to deploy remote MCP servers?\n\u003e Reach out to us at emcee@loopwork.com\n\n---\n\n## Why use emcee?\n\nMCP provides a standardized way to connect AI models to tools and data sources.\nIt's still early days, but there are already a variety of [available servers][mcp-servers]\nfor connecting to browsers, developer tools, and other systems.\n\nWe think emcee is a convenient way to connect to services\nthat don't have an existing MCP server implementation —\n_especially for services you're building yourself_.\nGot a web app with an OpenAPI spec?\nYou might be surprised how far you can get\nwithout a dashboard or client library.\n\n## Installation\n\n### Installer Script\n\nUse the [installer script][installer] to download and install a \n[pre-built release][releases] of emcee for your platform \n(Linux x86-64/i386/arm64 and macOS Intel/Apple Silicon).\n\n```console\n# fish\nsh (curl -fsSL https://get.emcee.sh | psub)\n\n# bash, zsh\nsh \u003c(curl -fsSL https://get.emcee.sh)\n```\n\n### Homebrew\n\nInstall emcee using [Homebrew][homebrew] from [Loopwork's tap][homebrew-tap].\n\n```console\nbrew install loopwork-ai/tap/emcee\n```\n\n### Docker\n\nPrebuilt [Docker images][docker-images] with emcee are available.\n\n```console\ndocker run -it ghcr.io/loopwork-ai/emcee\n```\n\n### Build From Source\n\nRequires [go 1.24][golang] or later.\n\n```console\ngit clone https://github.com/loopwork-ai/emcee.git\ncd emcee\ngo build -o emcee cmd/emcee/main.go\n```\n\nOnce built, you can run in place (`./emcee`)\nor move it somewhere in your `PATH`, like `/usr/local/bin`.\n\n## Usage\n\n```console\nUsage:\n  emcee [spec-path-or-url] [flags]\n\nFlags:\n      --basic-auth string    Basic auth value (either user:pass or base64 encoded, will be prefixed with 'Basic ')\n      --bearer-auth string   Bearer token value (will be prefixed with 'Bearer ')\n  -h, --help                 help for emcee\n      --raw-auth string      Raw value for Authorization header\n      --retries int          Maximum number of retries for failed requests (default 3)\n  -r, --rps int              Maximum requests per second (0 for no limit)\n  -s, --silent               Disable all logging\n      --timeout duration     HTTP request timeout (default 1m0s)\n  -v, --verbose              Enable debug level logging to stderr\n      --version              version for emcee\n```\n\nemcee implements [Standard Input/Output (stdio)](https://modelcontextprotocol.io/docs/concepts/transports#standard-input-output-stdio) transport for MCP,\nwhich uses [JSON-RPC 2.0](https://www.jsonrpc.org/) as its wire format.\n\nWhen you run emcee from the command-line,\nit starts a program that listens on stdin,\noutputs to stdout,\nand logs to stderr.\n\n### Authentication\n\nFor APIs that require authentication,\nemcee supports several authentication methods:\n\n| Authentication Type | Example Usage | Resulting Header |\n|------------------------|---------------|----------------------------|\n| **Bearer Token** | `--bearer-auth=\"abc123\"` | `Authorization: Bearer abc123` |\n| **Basic Auth** | `--basic-auth=\"user:pass\"` | `Authorization: Basic dXNlcjpwYXNz` |\n| **Raw Value** | `--raw-auth=\"Custom xyz789\"` | `Authorization: Custom xyz789` |\n\nThese authentication values can be provided directly\nor as [1Password secret references][secret-reference-syntax].\n\nWhen using 1Password references:\n- Use the format `op://vault/item/field`\n  (e.g. `--bearer-auth=\"op://Shared/X/credential\"`)\n- Ensure the 1Password CLI ([op][op]) is installed and available in your `PATH`\n- Sign in to 1Password before running emcee or launching Claude Desktop\n\n```console\n# Install op\nbrew install 1password-cli\n\n# Sign in 1Password CLI\nop signin\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"twitter\": {\n      \"command\": \"emcee\",\n      \"args\": [\n        \"--bearer-auth=op://shared/x/credential\",\n        \"https://api.twitter.com/2/openapi.json\"\n      ]\n    }\n  }\n}\n```\n\n\u003cimg src=\"https://github.com/user-attachments/assets/d639fd7c-f3bf-477c-9eb7-229285b36f7d\" alt=\"1Password Access Requested\" width=\"512\"\u003e\n\n\u003e [!IMPORTANT]  \n\u003e emcee doesn't use auth credentials when downloading \n\u003e OpenAPI specifications from URLs provided as command arguments.\n\u003e If your OpenAPI specification requires authentication to access,\n\u003e first download it to a local file using your preferred HTTP client,\n\u003e then provide the local file path to emcee.\n\n### Transforming OpenAPI Specifications\n\nYou can transform OpenAPI specifications before passing them to emcee using standard Unix utilities. This is useful for:\n- Selecting specific endpoints to expose as tools\n  with [jq][jq] or [yq][yq]\n- Modifying descriptions or parameters \n  with [OpenAPI Overlays][openapi-overlays]\n- Combining multiple specifications\n  with [Redocly][redocly-cli]\n\nFor example,\nyou can use `jq` to include only the `point` tool from `weather.gov`.\n\n```console\ncat path/to/openapi.json | \\\n  jq 'if .paths then .paths |= with_entries(select(.key == \"/points/{point}\")) else . end' | \\\n  emcee\n```\n\n\n### JSON-RPC\n\nYou can interact directly with the provided MCP server\nby sending JSON-RPC requests.\n\n\u003e [!NOTE]\n\u003e emcee provides only MCP tool capabilities.\n\u003e Other features like resources, prompts, and sampling aren't yet supported.\n\n#### List Tools\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eRequest\u003c/summary\u003e\n\n```json\n{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"params\": {}, \"id\": 1}\n```\n\n\u003c/details\u003e\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eResponse\u003c/summary\u003e\n\n```jsonc\n{\n  \"jsonrpc\":\"2.0\",\n  \"result\": {\n    \"tools\": [\n      // ...\n      {\n          \"name\": \"tafs\",\n          \"description\": \"Returns Terminal Aerodrome Forecasts for the specified airport station.\",\n          \"inputSchema\": {\n              \"type\": \"object\",\n              \"properties\": {\n                  \"stationId\": {\n                      \"description\": \"Observation station ID\",\n                      \"type\": \"string\"\n                  }\n              },\n              \"required\": [\"stationId\"]\n          }\n      },\n      // ...\n    ]\n  },\n  \"id\": 1\n}\n```\n\u003c/details\u003e\n\n#### Call Tool\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eRequest\u003c/summary\u003e\n\n```json\n{\"jsonrpc\": \"2.0\", \"method\": \"tools/call\", \"params\": { \"name\": \"taf\", \"arguments\": { \"stationId\": \"KPDX\" }}, \"id\": 1}\n```\n\n\u003c/details\u003e\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eResponse\u003c/summary\u003e\n\n```jsonc\n{\n  \"jsonrpc\":\"2.0\",\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": /* Weather forecast in GeoJSON format */,\n      \"annotations\": {\n        \"audience\": [\"assistant\"]\n      }\n    }\n  ]\n  \"id\": 1\n}\n```\n\n\u003c/details\u003e\n\n## Debugging\n\nThe [MCP Inspector][mcp-inspector] is a tool for testing and debugging MCP servers.\nIf Claude and/or emcee aren't working as expected,\nthe inspector can help you understand what's happening.\n\n```console\nnpx @modelcontextprotocol/inspector emcee https://api.weather.gov/openapi.json\n# 🔍 MCP Inspector is up and running at http://localhost:5173 🚀\n```\n\n```console\nopen http://localhost:5173\n```\n\n## License\n\nemcee is licensed under the Apache License, Version 2.0.\n\n[chatgpt-plugins]: https://openai.com/index/chatgpt-plugins/\n[claude]: https://claude.ai/download\n[docker-images]: https://github.com/loopwork-ai/emcee/pkgs/container/emcee\n[golang]: https://go.dev\n[homebrew]: https://brew.sh\n[homebrew-tap]: https://github.com/loopwork-ai/homebrew-tap\n[installer]: https://github.com/loopwork-ai/emcee/blob/main/tools/install.sh\n[jq]: https://github.com/jqlang/jq\n[mcp]: https://modelcontextprotocol.io/\n[mcp-clients]: https://modelcontextprotocol.info/docs/clients/\n[mcp-inspector]: https://github.com/modelcontextprotocol/inspector\n[mcp-servers]: https://modelcontextprotocol.io/examples\n[op]: https://developer.1password.com/docs/cli/get-started/\n[openapi]: https://openapi.org\n[openapi-overlays]: https://www.openapis.org/blog/2024/10/22/announcing-overlay-specification\n[redocly-cli]: https://redocly.com/docs/cli/commands\n[releases]: https://github.com/loopwork-ai/emcee/releases\n[secret-reference-syntax]: https://developer.1password.com/docs/cli/secret-reference-syntax/\n[yq]: https://github.com/mikefarah/yq","funding_links":[],"categories":["Recently Updated","openapi","Other Tools and Integrations","Large Language Models (LLMs)"],"sub_categories":["[Mar 08, 2025](/content/2025/03/08/README.md)","Model Context Protocol"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopwork-ai%2Femcee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floopwork-ai%2Femcee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopwork-ai%2Femcee/lists"}