{"id":27742447,"url":"https://github.com/ericflo/mcpman","last_synced_at":"2025-04-28T16:41:04.766Z","repository":{"id":289036914,"uuid":"969882170","full_name":"ericflo/mcpman","owner":"ericflo","description":"Manage and run MCP jobs","archived":false,"fork":false,"pushed_at":"2025-04-21T07:17:39.000Z","size":98,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-21T07:42:23.767Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/ericflo.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-04-21T05:04:13.000Z","updated_at":"2025-04-21T07:16:52.000Z","dependencies_parsed_at":"2025-04-21T07:55:52.672Z","dependency_job_id":null,"html_url":"https://github.com/ericflo/mcpman","commit_stats":null,"previous_names":["ericflo/mcpman"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Fmcpman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Fmcpman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Fmcpman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Fmcpman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericflo","download_url":"https://codeload.github.com/ericflo/mcpman/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251347572,"owners_count":21575105,"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":[],"created_at":"2025-04-28T16:41:03.782Z","updated_at":"2025-04-28T16:41:04.759Z","avatar_url":"https://github.com/ericflo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCPMan (MCP Manager)\n\nMCPMan orchestrates interactions between LLMs and Model Context Protocol (MCP) servers, making it easy to create powerful agentic workflows.\n\n## Quick Start\n\nRun MCPMan instantly without installing using `uvx`:\n\n```bash\n# Use the calculator server to perform math operations\nuvx mcpman -c server_configs/calculator_server_mcp.json -i openai -m gpt-4.1-mini -p \"What is 1567 * 329 and then divide by 58?\"\n\n# Use the datetime server to check time in different timezones\nuvx mcpman -c server_configs/datetime_server_mcp.json -i gemini -m gemini-2.0-flash-001 -p \"What time is it right now in Tokyo, London, and New York?\"\n\n# Use the filesystem server with Ollama for file operations\nuvx mcpman -c server_configs/filesystem_server_mcp.json -i ollama -m llama3:8b -p \"Create a file called example.txt with a sample Python function, then read it back to me\"\n\n# Use the filesystem server with LMStudio's local models\nuvx mcpman -c server_configs/filesystem_server_mcp.json -i lmstudio -m qwen2.5-7b-instruct-1m -p \"Create a simple JSON file with sample data and read it back to me\"\n```\n\nYou can also use `uv run` for quick one-off executions directly from GitHub:\n\n```bash\nuv run github.com/ericflo/mcpman -c server_configs/calculator_server_mcp.json -i openai -m gpt-4.1-mini -p \"What is 256 * 432?\"\n```\n\n## Core Features\n\n- **One-command setup**: Manage and launch MCP servers directly\n- **Tool orchestration**: Automatically connect LLMs to any MCP-compatible tool\n- **Detailed logging**: Structured JSON logs for every interaction with run ID tracking\n- **Log replay**: Visualize previous conversations with the mcpreplay tool\n- **Multiple LLM support**: Works with OpenAI, Google Gemini, Ollama, LMStudio and more\n- **Flexible configuration**: Supports stdio and SSE server communication\n\n## Installation\n\n```bash\n# Install with pip\npip install mcpman\n\n# Install with uv\nuv pip install mcpman\n\n# Install from GitHub\nuvx pip install git+https://github.com/ericflo/mcpman.git\n```\n\n## Basic Usage\n\n```bash\n# Run mode (default)\nmcpman -c \u003cCONFIG_FILE\u003e -i \u003cIMPLEMENTATION\u003e -m \u003cMODEL\u003e -p \"\u003cPROMPT\u003e\"\n\n# Replay mode\nmcpman --replay [--replay-file \u003cLOG_FILE\u003e]\n```\n\nExamples:\n\n```bash\n# Use local models with Ollama for filesystem operations\nmcpman -c ./server_configs/filesystem_server_mcp.json \\\n       -i ollama \\\n       -m codellama:13b \\\n       -p \"Create a simple bash script that counts files in the current directory and save it as count.sh\"\n\n# Use OpenAI with multi-server config\nmcpman -c ./server_configs/multi_server_mcp.json \\\n       -i openai \\\n       -m gpt-4.1-mini \\\n       -s \"You are a helpful assistant. Use tools effectively.\" \\\n       -p \"Calculate 753 * 219 and tell me what time it is in Sydney, Australia\"\n\n# Replay the most recent conversation\nmcpman --replay\n\n# Replay a specific log file\nmcpman --replay --replay-file ./logs/mcpman_20250422_142536.jsonl\n```\n\n## Server Configuration\n\nMCPMan uses JSON configuration files to define the MCP servers. Examples:\n\n**Calculator Server**:\n```json\n{\n  \"mcpServers\": {\n    \"calculator\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_servers.calculator\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n**DateTime Server**:\n```json\n{\n  \"mcpServers\": {\n    \"datetime\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_servers.datetime_utils\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n**Filesystem Server**:\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_servers.filesystem_ops\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n## Key Options\n\n| Option | Description |\n|--------|-------------|\n| `-c, --config \u003cPATH\u003e` | Path to MCP server config file |\n| `-i, --implementation \u003cIMPL\u003e` | LLM implementation (openai, gemini, ollama, lmstudio) |\n| `-m, --model \u003cMODEL\u003e` | Model name (gpt-4.1-mini, gemini-2.0-flash-001, llama3:8b, qwen2.5-7b-instruct-1m, etc.) |\n| `-p, --prompt \u003cPROMPT\u003e` | User prompt (text or file path) |\n| `-s, --system \u003cMESSAGE\u003e` | Optional system message |\n| `--base-url \u003cURL\u003e` | Custom endpoint URL |\n| `--temperature \u003cFLOAT\u003e` | Sampling temperature (default: 0.7) |\n| `--max-tokens \u003cINT\u003e` | Maximum response tokens |\n| `--no-verify` | Disable task verification |\n| `--strict-tools` | Enable strict mode for tool schemas (default) |\n| `--no-strict-tools` | Disable strict mode for tool schemas |\n| `--replay` | Run in replay mode to visualize a previous conversation log |\n| `--replay-file \u003cPATH\u003e` | Path to the log file to replay (defaults to latest log) |\n\nAPI keys are set via environment variables: `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.  \nTool schema behavior can be configured with the `MCPMAN_STRICT_TOOLS` environment variable.\n\n## Why MCPMan?\n\n- **Standardized interaction**: Unified interface for diverse tools\n- **Simplified development**: Abstract away LLM-specific tool call formats\n- **Debugging support**: Detailed JSONL logs for every step in the agent process \n- **Local or cloud**: Works with both local and cloud-based LLMs\n\n## Currently Supported LLMs\n\n- OpenAI (GPT-4.1, GPT-4.1-mini, GPT-4.1-nano)\n- Anthropic Claude (claude-3-7-sonnet-20250219, etc.)\n- Google Gemini (gemini-2.0-flash-001, etc.)\n- OpenRouter\n- Ollama (llama3, codellama, etc.)\n- LM Studio (Qwen, Mistral, and other local models)\n\n## Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/ericflo/mcpman.git\ncd mcpman\n\n# Create environment and install deps\nuv venv\nsource .venv/bin/activate  # Linux/macOS\n# or .venv\\Scripts\\activate  # Windows\nuv pip install -e \".[dev]\"\n\n# Run tests\npytest tests/\n```\n\n## Project Structure\n\n- `src/mcpman/`: Core source code\n- `mcp_servers/`: Example MCP servers for testing\n- `server_configs/`: Example configuration files\n- `logs/`: Auto-generated structured JSONL logs\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericflo%2Fmcpman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericflo%2Fmcpman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericflo%2Fmcpman/lists"}