{"id":24401615,"url":"https://github.com/hideya/mcp-client-langchain-py","last_synced_at":"2025-07-27T18:12:43.027Z","repository":{"id":272193481,"uuid":"915763111","full_name":"hideya/mcp-client-langchain-py","owner":"hideya","description":"Simple MCP Client CLI Implementation Using LangChain ReAct Agent / Python","archived":false,"fork":false,"pushed_at":"2025-07-05T17:10:31.000Z","size":333,"stargazers_count":9,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-05T17:35:51.486Z","etag":null,"topics":["langchain","langchain-python","mcp","mcp-client","modelcontextprotocol","python","tool-call","tool-calling"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hideya.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,"zenodo":null}},"created_at":"2025-01-12T18:28:40.000Z","updated_at":"2025-07-05T17:10:34.000Z","dependencies_parsed_at":"2025-02-12T08:37:47.147Z","dependency_job_id":"b63a98eb-ed9f-41b8-beca-a1a5404277bf","html_url":"https://github.com/hideya/mcp-client-langchain-py","commit_stats":null,"previous_names":["hideya/mcp-client-langchain-py"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hideya/mcp-client-langchain-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideya%2Fmcp-client-langchain-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideya%2Fmcp-client-langchain-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideya%2Fmcp-client-langchain-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideya%2Fmcp-client-langchain-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hideya","download_url":"https://codeload.github.com/hideya/mcp-client-langchain-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hideya%2Fmcp-client-langchain-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267400520,"owners_count":24081183,"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","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["langchain","langchain-python","mcp","mcp-client","modelcontextprotocol","python","tool-call","tool-calling"],"created_at":"2025-01-20T00:32:34.461Z","updated_at":"2025-07-27T18:12:43.021Z","avatar_url":"https://github.com/hideya.png","language":"Python","funding_links":[],"categories":["🤖 AI/ML"],"sub_categories":[],"readme":"# Simple MCP Client to Explore MCP Servers / Python [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/hideya/langchain-mcp-tools-py/blob/main/LICENSE) [![pypi version](https://img.shields.io/pypi/v/mcp-chat.svg)](https://pypi.org/project/mcp-chat/)\n\n\n**Quickly test and explore MCP servers from the command line!**\n\nA simple, text-based CLI client for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers built with LangChain and Python.  \nSuitable for testing MCP servers, exploring their capabilities, and prototyping integrations.\n\nInternally it uses [LangChain ReAct Agent](https://langchain-ai.github.io/langgraph/reference/agents/) and\na utility function `convert_mcp_to_langchain_tools()` from [`langchain_mcp_tools`](https://pypi.org/project/langchain-mcp-tools/).  \n\nA TypeScript equivalent of this utility is available [here](https://www.npmjs.com/package/@h1deya/mcp-try-cli)\n\n## Prerequisites\n\n- Python 3.11+\n- [optional] [`uv` (`uvx`)](https://docs.astral.sh/uv/getting-started/installation/)\n  installed to run Python package-based MCP servers\n- [optional] [npm 7+ (`npx`)](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)\n  to run Node.js package-based MCP servers\n- LLM API keys from\n  [OpenAI](https://platform.openai.com/api-keys),\n  [Anthropic](https://console.anthropic.com/settings/keys),\n  and/or\n  [Google GenAI](https://aistudio.google.com/apikey)\n  as needed\n\n## Quick Start\n\n- Install `mcp-chat` tool.\n  This can take up to a few minutes to complete:\n  ```bash\n  pip install mcp-chat\n  ```\n\n- Configure LLM and MCP Servers settings via the configuration file, `llm_mcp_config.json5`\n  ```bash\n  code llm_mcp_config.json5\n  ```\n\n  The following is a simple configuration for quick testing:\n  ```json5\n  {\n    \"llm\": {\n      \"model_provider\": \"openai\",\n      \"model\": \"gpt-4o-mini\",\n      // \"model_provider\": \"anthropic\",\n      // \"model\": \"claude-3-5-haiku-latest\",\n      // \"model_provider\": \"google_genai\",\n      // \"model\": \"gemini-2.0-flash\",\n    },\n\n    \"mcp_servers\": {\n      \"us-weather\": {  // US weather only\n        \"command\": \"npx\", \n        \"args\": [\"-y\", \"@h1deya/mcp-server-weather\"]\n      },\n    },\n\n    \"example_queries\": [\n      \"Tell me how LLMs work in a few sentences\",\n      \"Are there any weather alerts in California?\",\n    ],\n  }\n  ```\n\n- Set up API keys\n  ```bash\n  echo \"ANTHROPIC_API_KEY=sk-ant-...                                       \n  OPENAI_API_KEY=sk-proj-...\n  GOOGLE_API_KEY=AI...\" \u003e .env\n  \n  code .env\n  ```\n\n- Run the tool\n  ```bash\n  mcp-chat\n  ```\n  By default, it reads the configuration file, `llm_mcp_config.json5`, from the current directory.  \n  Then, it applies the environment variables specified in the `.env` file,\n  as well as the ones that are already defined.\n\n## Building from Source\n\nSee [README_DEV.md](https://github.com/hideya/mcp-client-langchain-py/blob/main/README_DEV.md) for details.\n\n## Features\n\n- **Easy setup**: Works out of the box with popular MCP servers\n- **Flexible configuration**: JSON5 config with environment variable support\n- **Multiple LLM providers**: OpenAI, Anthropic, Google (GenAI)\n- **Command \u0026 URL servers**: Support for both local and remote MCP servers\n- **Local MCP Server logging**: Save stdio MCP server logs with customizable log directory\n- **Interactive testing**: Example queries for the convenience of repeated testing\n\n## Limitations\n\n- **Tool Return Types**: Currently, only text results of tool calls are supported.\nIt uses LangChain's `response_format: 'content'` (the default) internally, which only supports text strings.\nWhile MCP tools can return multiple content types (text, images, etc.), this library currently filters and uses only text content.\n- **MCP Features**: Only MCP [Tools](https://modelcontextprotocol.io/docs/concepts/tools) are supported. Other MCP features like Resources, Prompts, and Sampling are not implemented.\n\n## Usage\n\n### Basic Usage\n\n```bash\nmcp-chat\n```\n\nBy default, it reads the configuration file, `llm_mcp_config.json5`, from the current directory.  \nThen, it applies the environment variables specified in the `.env` file,\nas well as the ones that are already defined.  \nIt outputs local MCP server logs to the current directory.\n\n### With Options\n\n```bash\n# Specify the config file to use\nmcp-chat --config my-config.json5\n\n# Store local (stdio) MCP server logs in specific directory\nmcp-chat --log-dir ./logs\n\n# Enable verbose logging\nmcp-chat --verbose\n\n# Show help\nmcp-chat --help\n```\n\n## Supported LLM Providers\n\n- **OpenAI**: `gpt-4o`, `gpt-4o-mini`, etc.\n- **Anthropic**: `claude-sonnet-4-0`, `claude-3-5-haiku-latest`, etc.\n- **Google (GenAI)**: `gemini-2.0-flash`, `gemini-1.5-pro`, etc.\n\n## Configuration\n\nCreate a `llm_mcp_config.json5` file:\n\n- [The configuration file format](https://github.com/hideya/mcp-client-langchain-py/blob/main/llm_mcp_config.json5)\n  for MCP servers follows the same structure as\n  [Claude for Desktop](https://modelcontextprotocol.io/quickstart/user),\n  with one difference: the key name `mcpServers` has been changed\n  to `mcp_servers` to follow the snake_case convention\n  commonly used in JSON configuration files.\n- The file format is [JSON5](https://json5.org/),\n  where comments and trailing commas are allowed.\n- The format is further extended to replace `${...}` notations\n  with the values of corresponding environment variables.\n- Keep all the credentials and private info in the `.env` file\n  and refer to them with `${...}` notation as needed\n\n```json5\n{\n  \"llm\": {\n    \"model_provider\": \"openai\",\n    \"model\": \"gpt-4.1-nano\",\n    // model: \"o4-mini\",\n  },\n  \n  // \"llm\": {\n  //   \"model_provider\": \"anthropic\",\n  //   \"model\": \"claude-3-5-haiku-latest\",\n  //   // \"model\": \"claude-sonnet-4-0\",\n  // },\n\n  // \"llm\": {\n  //   \"model_provider\": \"google_genai\",\n  //   \"model\": \"gemini-2.5-flash\",\n  //   // \"model\": \"gemini-2.5-pro\",\n  // }\n\n  \"example_queries\": [\n    \"Tell me how LLMs work in a few sentences\",\n    \"Are there any weather alerts in California?\",\n    \"Read the news headlines on bbc.com\",\n  ],\n\n  \"mcp_servers\": {\n    // Local MCP server that uses `npx`\n    \"weather\": {\n      \"command\": \"npx\", \n      \"args\": [ \"-y\", \"@h1deya/mcp-server-weather\" ]\n    },\n\n    // Another local server that uses `uvx`\n    \"fetch\": {\n      \"command\": \"uvx\",\n      \"args\": [ \"mcp-server-fetch\" ]\n    },\n\n    \"brave-search\": {\n      \"command\": \"npx\",\n      \"args\": [ \"-y\", \"@modelcontextprotocol/server-brave-search\" ],\n      \"env\": { \"BRAVE_API_KEY\": \"${BRAVE_API_KEY}\" }\n    },\n\n    // Remote MCP server via URL\n    // Auto-detection: tries Streamable HTTP first, falls back to SSE\n    \"remote-mcp-server\": {\n      \"url\": \"https://api.example.com/...\"\n    },\n\n    // Server with authentication\n    \"github\": {\n      \"type\": \"http\",  // recommended to specify the protocol explicitly when authentication is used\n      \"url\": \"https://api.githubcopilot.com/mcp/\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\nCreate a `.env` file for API keys:\n\n```bash\nOPENAI_API_KEY=sk-ant-...\nANTHROPIC_API_KEY=sk-proj-...\nGOOGLE_API_KEY=AI...\n\n# Other services as needed\nGITHUB_PERSONAL_ACCESS_TOKEN=github_pat_...\nBRAVE_API_KEY=BSA...\n```\n\n## Popular MCP Servers to Try\n\nThere are quite a few useful MCP servers already available:\n\n- [MCP Server Listing on the Official Site](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#model-context-protocol-servers)\n\n## Troubleshooting\n\n- Make sure your configuration and .env files are correct, especially the spelling of the API keys\n- Check the local MCP server logs\n- Use `--verbose` flag to view the detailed logs\n- Refer to [Debugging Section in MCP documentation](https://modelcontextprotocol.io/docs/tools/debugging)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nIssues and pull requests welcome! This tool aims to make MCP server testing as simple as possible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhideya%2Fmcp-client-langchain-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhideya%2Fmcp-client-langchain-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhideya%2Fmcp-client-langchain-py/lists"}