{"id":28366819,"url":"https://github.com/http4k/mcp-desktop","last_synced_at":"2026-04-26T22:01:04.531Z","repository":{"id":282095495,"uuid":"947436661","full_name":"http4k/mcp-desktop","owner":"http4k","description":"http4k MCP Desktop Client","archived":false,"fork":false,"pushed_at":"2026-04-12T19:16:21.000Z","size":293,"stargazers_count":39,"open_issues_count":3,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-04-12T21:15:16.827Z","etag":null,"topics":["llm","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"https://mcp.http4k.org","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/http4k.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"http4k"}},"created_at":"2025-03-12T17:25:45.000Z","updated_at":"2026-04-03T19:39:43.000Z","dependencies_parsed_at":"2025-03-30T08:25:32.647Z","dependency_job_id":"495a5b8f-ae54-4d5f-8d7d-79fa620a18d3","html_url":"https://github.com/http4k/mcp-desktop","commit_stats":null,"previous_names":["http4k/http4k-mcp-desktop"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/http4k/mcp-desktop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/http4k%2Fmcp-desktop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/http4k%2Fmcp-desktop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/http4k%2Fmcp-desktop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/http4k%2Fmcp-desktop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/http4k","download_url":"https://codeload.github.com/http4k/mcp-desktop/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/http4k%2Fmcp-desktop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32314116,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T21:09:39.134Z","status":"ssl_error","status_checked_at":"2026-04-26T21:09:21.240Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["llm","modelcontextprotocol"],"created_at":"2025-05-29T00:12:19.440Z","updated_at":"2026-04-26T22:01:04.524Z","avatar_url":"https://github.com/http4k.png","language":"Kotlin","readme":"# http4k MCP Desktop Client\n\n[![http4k Logo](http4k-mcp.png)](https://mcp.http4k.org)\n\nA command-line desktop client for connecting to MCP (Model Context Protocol) servers via standard input/output (StdIO). This client is designed to work\nseamlessly with AI assistants and applications that communicate through StdIO, such as Claude and other desktop AI applications.\n\n## Overview\n\nThe http4k MCP Desktop Client serves as a proxy that enables communication between desktop applications and MCP servers. While it works with any MCP-compliant\nserver, it's specially optimized for servers built using the [http4k MCP SDK](https://mcp.http4k.org).\n\n## Features\n\n- Multiple remote transport options: HTTP Streaming, SSE (Server-Sent Events), JSON-RPC, WebSocket\n- Various authentication methods: API Key, Bearer Token, Basic Auth, and OAuth\n- Customizable reconnection strategy\n- Simple StdIO interface for easy integration with desktop applications when using natively compiled Kotlin apps.\n\n### Remote Protocol Comparison\n\nThe [MCP Standard](https://spec.modelcontextprotocol.io/) remote protocol is HTTP Streaming, which superceded the previous standard (SSE) in the `2025-03-26` version. http4k has implemented other standard transports into the http4k-mcp-desktop, as these will be more appropriate for distributed/hosted MCP servers.\n\n| Protocol           | Standard/Extension | State     | Default server path   | Setting     |Description                                                                                   |\n|--------------------|--------------------|-----------|-----------------------|-----------|------------------------------------------------------------------------------------|\n| HTTP Non-streaming | MCP Standard       | Stateless | `http://host/mcp`     | `http-nonstream` | Pure HTTP-based streaming communication  **Use this setting for Cursor!**                                                    |\n| HTTP Streaming     | MCP Standard       | Stateful  | `http://host/mcp`     | `http-stream` | HTTP/SSE-based streaming communication. Supports sessions and replaying/reconnection of stram |\n| SSE                | MCP (Legacy)       | Stateful  | `http://host/sse`     | `sse` | Server-Sent Events, part of HTML5 spec, ideal for streaming data from server to client        |\n| WebSocket          | Protocol Extension | Stateful  | `http://host/ws`      | `websocket` | Full-duplex communication protocol, maintains persistent connection                           |\n| JSON-RPC           | Protocol Extension | Stateless | `http://host/jsonrpc` | `jsonrpc` | Remote Procedure Call protocol encoded in JSON, request/response model                        |\n\n## Installation\n\n### Via Homebrew\n\n```bash\nbrew tap http4k/tap\nbrew install http4k-mcp-desktop\n```\n\n### Via GitHub Releases\n\nDownload the latest release from [GitHub Releases](https://github.com/http4k/http4k-mcp-desktop/releases).\n\n## Usage\n\n```bash\nhttp4k-mcp-desktop --url http://localhost:3001/\u003cprotocol\u003e [OPTIONS]\n```\n\n## Command Line Options\n\n| Option             | Description                                                                                                             | Default       |\n|--------------------|-------------------------------------------------------------------------------------------------------------------------|---------------|\n| `--transport`      | MCP transport mode: `http-stream`, `http-nonstream`, `sse` (legacy), `jsonrpc` (non-streaming), `websocket` (streaming) | `http-stream` |\n| `--url`            | URL of the MCP server to connect to (required)                                                                          | N/A           |\n| `--reconnectDelay` | Reconnect delay in seconds if disconnected                                                                              | 0             |\n| `--version`        | Get the version information for the app                                                                                 | N/A           |\n\n### Authentication Options\n\nAt time of writing, the MCP auth standards are in flux, but http4k-mcp-desktop has implemented some standard HTTP mechanisms into the http4k-mcp-desktop.\n\n- Basic Auth\n- Bearer Token\n- API Key\n- *OAuth via standardised auto-discovery\n\n* This is the OAuth standard which is currently in the post 2025-03-26 draft specification which uses auto discovery of the authentication token using \nOAuth Protected Resource and OAuth Client Credentials. This requires:\n\n  - The MCP server to list its authentication servers in it's OAuth Protected Resource metadata endpoint (`/.well-knwon/oauth-protected-resource`)\n  - The Authentication server to support the OAuth Client Credentials flow and auto discovery endpoint (`/.well-knwon/oauth-authorization-server`)\n\nMCP servers built using the [http4k MCP SDK](https://mcp.http4k.org) do support the above, but other servers may not.\n\n| Option                     | Description                            | Format                |\n|----------------------------|----------------------------------------|-----------------------|\n| `--apiKey`                 | API key for server authentication      | String                |\n| `--apiKeyHeader`           | Custom header name for API key         | `X-Api-key` (default) |\n| `--bearerToken`            | Bearer token for server authentication | String                |\n| `--basicAuth`              | Basic authentication credentials       | `\u003cuser\u003e:\u003cpassword\u003e`   |\n| `--oauthScopes`            | OAuth scopes to request                | Comma-separated list  |\n| `--oauthClientCredentials` | OAuth client credentials               | `\u003cclient\u003e:\u003csecret\u003e`   |\n\n\n## Examples\n\n### Basic connection: HTTP Streaming (HTTP+SSE) HTTP Connection\n\n```bash\nhttp4k-mcp-desktop --url http://localhost:3001/mcp\n...or\nhttp4k-mcp-desktop --url http://localhost:3001/mcp --transport http-stream\n```\n\n### Basic connection: HTTP Non-streaming (HTTP) + Cursor\n\n```bash\nhttp4k-mcp-desktop --url http://localhost:3001/mcp --transport http-nonstream\n```\n\n### Basic SSE Connection (legacy MCP standard)\n\n```bash\nhttp4k-mcp-desktop --url http://localhost:3001/sse --transport sse\n```\n\n### HTTP Streaming with auto-discovered (Protected Resource) OAuth Authentication.\n\n```bash\nhttp4k-mcp-desktop --url http://localhost:3001/mcp --oauthClientCredentials client:secret\n```\n\n### JSON-RPC with API Key Auth w\n\n```bash\nhttp4k-mcp-desktop --transport jsonrpc --url http://localhost:3001/jsonrpc --apiKey your-api-key\n```\n\n### WebSocket with Bearer Token and Reconnect\n\n```bash\nhttp4k-mcp-desktop --transport websocket --url ws://localhost:3001/ws --bearerToken your-token --reconnectDelay 5\n```\n\n## Integration with AI Applications\n\nThis client is specifically designed to work with desktop AI applications that use StdIO for communication. It handles:\n\n1. Reading input from the AI application via stdin\n2. Sending that input to the MCP server\n3. Receiving responses from the server\n4. Passing those responses back to the application via stdout\n\nThis enables seamless connections between desktop AI applications like Claude and remote MCP servers.\n\n### Configuring Claude Desktop\n\nTo configure Claude Desktop to use the http4k MCP Desktop Client, you'll need to create a JSON configuration file. Note that if you're on mac and installed the\napp via Brew, it will already be on your path. Here's how to set it up:\n\n1. Create a `config.json` file with the following structure:\n\n```json\n{\n    \"command\": \"/path/to/http4k-mcp-desktop\",\n    \"args\": [\n        \"--url\",\n        \"http://your-mcp-server:port/mcp\"\n    ],\n    \"env\": {}\n}\n```\n\n2. Adjust the parameters as needed:\n    - Update the path to where you've installed the http4k-mcp-desktop binary. For brew users it's already on your path so just use `http4k-mcp-desktop`\n    - Set the correct URL and protocol options for your MCP server (see examples)\n    - Add any authentication options required (see examples)\n\n3. In the Claude Desktop application settings, specify the path to your `config.json` file.\n\n#### Example Configurations\n\n**Basic MCP Server Connection:**\n\n```json\n{\n    \"command\": \"/usr/local/bin/http4k-mcp-desktop\",\n    \"args\": [\n        \"--url\",\n        \"http://localhost:3001/sse\"\n    ],\n    \"env\": {}\n}\n```\n\n**With API Key Authentication:**\n\n```json\n{\n    \"command\": \"/usr/local/bin/http4k-mcp-desktop\",\n    \"args\": [\n        \"--url\",\n        \"http://localhost:3001/sse\",\n        \"--apiKey\",\n        \"your-api-key\"\n    ],\n    \"env\": {}\n}\n```\n\n**With OAuth Authentication:**\n\n```json\n{\n    \"command\": \"/usr/local/bin/http4k-mcp-desktop\",\n    \"args\": [\n        \"--url\",\n        \"http://localhost:3001/sse\",\n        \"--oauthTokenUrl\",\n        \"http://localhost:3001/token\",\n        \"--oauthClientCredentials\",\n        \"client:secret\"\n    ],\n    \"env\": {}\n}\n```\n\n## Learn More\n\n- [Model Context Protocol](https://modelcontextprotocol.io/) - Learn about the MCP specification\n- [http4k MCP SDK](https://mcp.http4k.org) - Explore the http4k MCP server implementation\n\n## FAQ\n\n- **Q:** I'm using Cursor but I get an error message when installing my MCP connection \n- **A:** Cursor users should currently use HTTP Non-streaming mode (`--transport http-nonstream`)\n\n## License\n\nThis project is licensed under the [http4k Commercial License](https://www.http4k.org/commercial-license/), which is totally free for non-commercial, non-profit\nand research use.\n","funding_links":["https://github.com/sponsors/http4k"],"categories":["📚 Projects (2474 total)"],"sub_categories":["MCP Servers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttp4k%2Fmcp-desktop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhttp4k%2Fmcp-desktop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttp4k%2Fmcp-desktop/lists"}