Skip to content
Back to search

mcp-chat

Open Source Generic MCP Client for testing & evaluating mcp servers and agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/flux159--mcp-chat/badge.svg)](/listings/flux159--mcp-chat)

HTML

<a href="/listings/flux159--mcp-chat"><img src="/api/listings/flux159--mcp-chat/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Make sure that you have `ANTHROPIC_API_KEY` exported in your environment or in a .env file in the root of the project. You can get an API key by signing up at the [Anthropic Console keys page](https://console.anthropic.com/settings/keys).

Simple use case that spawns an interactive chat prompt with the filesystem MCP server from CLI:

npx mcp-chat --server "npx -y @modelcontextprotocol/server-filesystem /Users/$USER/Desktop"

This will open up a chat prompt that you can use to interact with the servers and chat with an LLM.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 217 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # mcp-chat
  2. <div align="right">
  3. <details>
  4. <summary >🌐 Language</summary>
  5. <div>
  6. <div align="center">
  7. <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=en">English</a>
  8. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=zh-CN">简体中文</a>
  9. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=zh-TW">繁體中文</a>
  10. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=ja">日本語</a>
  11. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=ko">한국어</a>
  12. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=hi">हिन्दी</a>
  13. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=th">ไทย</a>
  14. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=fr">Français</a>
  15. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=de">Deutsch</a>
  16. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=es">Español</a>
  17. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=it">Italiano</a>
  18. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=ru">Русский</a>
  19. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=pt">Português</a>
  20. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=nl">Nederlands</a>
  21. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=pl">Polski</a>
  22. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=ar">العربية</a>
  23. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=fa">فارسی</a>
  24. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=tr">Türkçe</a>
  25. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=vi">Tiếng Việt</a>
  26. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=id">Bahasa Indonesia</a>
  27. | <a href="https://openaitx.github.io/view.html?user=Flux159&project=mcp-chat&lang=as">অসমীয়া</
  28. </div>
  29. </div>
  30. </details>
  31. </div>
  32. Open Source Generic MCP Client for testing & evaluating mcp servers and agents
  33. <p align="center">
  34. <img width="600" src="https://raw.githubusercontent.com/Flux159/mcp-chat/refs/heads/main/mcpchat.svg">
  35. </p>
  36. ## Quickstart
  37. Make sure that you have `ANTHROPIC_API_KEY` exported in your environment or in a .env file in the root of the project. You can get an API key by signing up at the [Anthropic Console keys page](https://console.anthropic.com/settings/keys).
  38. Simple use case that spawns an interactive chat prompt with the filesystem MCP server from CLI:
  39. ```shell
  40. npx mcp-chat --server "npx -y @modelcontextprotocol/server-filesystem /Users/$USER/Desktop"
  41. ```
  42. This will open up a chat prompt that you can use to interact with the servers and chat with an LLM.
  43. ## Config
  44. You can also just specify your claude_desktop_config.json (Mac):
  45. ```shell
  46. npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"
  47. ```
  48. Or (Windows):
  49. ```shell
  50. npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"
  51. ```
  52. ## Web mode
  53. https://github.com/user-attachments/assets/b7e8a648-8084-4955-8cdf-fc6eb141572e
  54. You can also run mcp-chat in web mode by specifying the `--web` flag (make sure to have `ANTHROPIC_API_KEY` exported in your environment):
  55. ```shell
  56. npx mcp-chat --web
  57. ```
  58. In web mode, you can start new chats, send messages to the model, and dynamically configure the mcp servers via the UI - no need to specify on the command line. In addition, chats created via the Web UI are saved to ~/.mcpchats/chats just like chats created via the CLI.
  59. ## Features
  60. - [x] Run via CLI in interactive mode or directly pass prompts with `-p`
  61. - [x] Web mode to chat with models via a web interface `--web`
  62. - [x] Connect to any MCP server (JS, Python, Docker) in production or during development
  63. - [x] Choose between models with `-m`
  64. - [x] Customize system prompt with `--system`
  65. - [x] Saves chat history with settings in `~/.mcpchat/chats` including web chats
  66. - [x] Save and restore commands in `~/.mcpchat/history`
  67. - [x] View tool call output and arguments directly in chat to help debug mcp servers
  68. ## CLI Usage
  69. Run prompts via CLI with the `-p` flag:
  70. ```shell
  71. npx mcp-chat --server "npx mcp-server-kubernetes" -p "List the pods in the default namespace"
  72. ```
  73. This runs the prompt with the kubenertes mcp-server & exits after the response is received on stdout.
  74. Choose a model to chat with via CLI with the `-m` flag:
  75. ```shell
  76. npx mcp-chat --server "npx mcp-server-kubernetes" -m "claude-3.5"
  77. ```
  78. Uses the model `claude-3.5` to chat with. Note that currently only Anthropic models are supported.
  79. Custom system prompt:
  80. `--system` flag can be used to specify a system prompt:
  81. ```shell
  82. npx mcp-chat --system "Explain the output to the user in pirate speak." --server "npx mcp-server-kubernetes" -p "List the pods in the default namespace"
  83. ```
  84. ## Remote MCP servers
  85. Pass a [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) endpoint URL to `--server` instead of a local command:
  86. ```shell
  87. npx mcp-chat --server "https://example.com/mcp" -p "What tools do you have available?"
  88. ```
  89. Any `http://` or `https://` server string is treated as a Streamable HTTP endpoint, both in the CLI and in web mode chat settings. Legacy SSE endpoints and servers that require authentication are not currently supported.
  90. ## ENV vars
  91. Mcp-chat supports passing through env vars to mcp servers. This is not standardized in the mcp spec though and other clients may not do this with dynamic env var values - read more [here](https://github.com/Flux159/mcp-server-kubernetes/issues/148#issuecomment-2950181666) about standard stdio mcp clients.
  92. ```shell
  93. KUBECONFIG="~/.kube/config" npx mcp-chat --server "npx mcp-server-kubernetes"
  94. ```
  95. ## For developers of mcp-servers
  96. You can pass in a local build of a python or node mcp-server to test it out with mcp-chat:
  97. Node JS:
  98. ```shell
  99. # Directly executing built script
  100. npx mcp-chat --server "/path/to/mcp-server-kubernetes/dist/index.js"
  101. # Using node / bun
  102. npx mcp-chat --server "node /path/to/mcp-server-kubernetes/dist/index.js"
  103. ```
  104. Python:
  105. ```shell
  106. # Python: Using uv
  107. npx mcp-chat --server "uv --directory /path/to/mcp-server-weather/ run weather.py"
  108. # Using python / python3 - make sure to run in venv or install deps globally
  109. npx mcp-chat --server "/path/to/mcp-server-weather/weather.py"
  110. ```
  111. ## Development
  112. Install dependencies & run the CLI:
  113. ```shell
  114. git clone https://github.com/Flux159/mcp-chat
  115. bun install
  116. bun run dev
  117. ```
  118. To develop mcp-chat while connecting to an mcp-server, make a build & run the CLI with the server flag:
  119. ```shell
  120. npm run build && node dist/index.js --server "npx mcp-server-kubernetes" -p "List the pods in the default namespace"
  121. ```
  122. Testing:
  123. ```shell
  124. bun run test
  125. ```
  126. Building:
  127. ```shell
  128. bun run build
  129. ```
  130. Publishing:
  131. ```shell
  132. bun run publish
  133. ```
  134. Publishing Docker:
  135. ```shell
  136. bun run dockerbuild
  137. ```
  138. ### Project Structure
  139. ```
  140. ├── src/
  141. │ ├── index.ts # Main client implementation & CLI params
  142. │ ├── constants.ts # Default constants
  143. │ ├── interactive.ts # Interactive chat prompt handling & logic
  144. ├── test/ # Test files
  145. │ ├── cli.test.ts # Test CLI params
  146. │ ├── config.test.ts # Test config file parsing
  147. ```
  148. ## Publishing new release
  149. Go to the [releases](https://github.com/Flux159/mcp-chat/releases) page, click on "Draft New Release", click "Choose a tag" and create a new tag by typing out a new version number using "v{major}.{minor}.{patch}" semver format. Then, write a release title "Release v{major}.{minor}.{patch}" and description / changelog if necessary and click "Publish Release".
  150. This will create a new tag which will trigger a new release build via the cd.yml workflow. Once successful, the new release will be published to npm. Note that there is no need to update the package.json version manually, as the workflow will automatically update the version number in the package.json file & push a commit to main.
  151. ## License
  152. [MIT License](https://github.com/Flux159/mcp-chat/blob/main/LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.