{"id":26127725,"url":"https://github.com/dylibso/mcpx-py","last_synced_at":"2025-04-13T17:22:54.758Z","repository":{"id":271311675,"uuid":"898711034","full_name":"dylibso/mcpx-py","owner":"dylibso","description":"Python client library for https://mcp.run - call portable \u0026 secure tools for your AI Agents and Apps","archived":false,"fork":false,"pushed_at":"2025-03-20T18:02:08.000Z","size":596,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-27T08:11:37.842Z","etag":null,"topics":["agents","ai","llm","mcp","mcp-client","mcp-run","mcp-server","python"],"latest_commit_sha":null,"homepage":"https://docs.mcp.run","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dylibso.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":"2024-12-04T22:21:56.000Z","updated_at":"2025-03-20T18:01:28.000Z","dependencies_parsed_at":"2025-01-28T02:27:47.073Z","dependency_job_id":"78aeaf8a-8c5a-4693-bf28-dde75fa4d2f0","html_url":"https://github.com/dylibso/mcpx-py","commit_stats":null,"previous_names":["dylibso/mcpx-py"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmcpx-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmcpx-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmcpx-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmcpx-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dylibso","download_url":"https://codeload.github.com/dylibso/mcpx-py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248750872,"owners_count":21155797,"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","ai","llm","mcp","mcp-client","mcp-run","mcp-server","python"],"created_at":"2025-03-10T18:36:16.475Z","updated_at":"2025-04-13T17:22:54.750Z","avatar_url":"https://github.com/dylibso.png","language":"Python","funding_links":[],"categories":["📚 Projects (2474 total)"],"sub_categories":["MCP Clients"],"readme":"# mcpx-py\n[![PyPI](https://img.shields.io/pypi/v/mcpx-py)](https://pypi.org/project/mcpx-py/)\n\nA Python library for interacting with LLMs using mcp.run tools\n\n## Features\n\n### AI Provider Support\n\n`mcpx-py` supports all models supported by [PydanticAI](https://ai.pydantic.dev/models/)\n\n## Dependencies\n\n- `uv`\n- `npm`\n- `ollama` (optional)\n\n## mcp.run Setup\n\nYou will need to get an mcp.run session ID by running:\n\n```bash\nnpx --yes -p @dylibso/mcpx gen-session --write\n```\n\nThis will generate a new session and write the session ID to a configuration file that can be used\nby `mcpx-py`.\n \nIf you need to store the session ID in  an environment variable you can run `gen-session`\nwithout the `--write` flag:\n\n```bash\nnpx --yes -p @dylibso/mcpx gen-session\n```\n\nwhich should output something like:\n\n```\nLogin successful!\nSession: kabA7w6qH58H7kKOQ5su4v3bX_CeFn4k.Y4l/s/9dQwkjv9r8t/xZFjsn2fkLzf+tkve89P1vKhQ\n```\n\nThen set the `MPC_RUN_SESSION_ID` environment variable:\n\n```\n$ export MCP_RUN_SESSION_ID=kabA7w6qH58H7kKOQ5su4v3bX_CeFn4k.Y4l/s/9dQwkjv9r8t/xZFjsn2fkLzf+tkve89P1vKhQ\n```\n\n## Python Usage\n\n### Installation\n\nUsing `uv`:\n\n```bash\nuv add mcpx-py\n```\n\nOr `pip`:\n\n```bash\npip install mcpx-py\n```\n\n### Example code\n\n```python\nfrom mcpx_py import Chat\n\nllm = Chat(\"claude-3-5-sonnet-latest\")\n\n# Or OpenAI\n# llm = Chat(\"gpt-4o\")\n\n# Or Ollama\n# llm = Chat(\"ollama:qwen2.5\")\n\n# Or Gemini\n# llm = Chat(\"gemini-2.0-flash\")\n\nresponse = llm.send_message_sync(\n    \"summarize the contents of example.com\"\n)\nprint(response.data)\n```\n\nIt's also possible to get structured output by setting `result_type`\n\n```python\nfrom mcpx_py import Chat, BaseModel, Field\nfrom typing import List\n\nclass Summary(BaseModel):\n    \"\"\"\n    A summary of some longer text\n    \"\"\"\n    source: str = Field(\"The source of the original_text\")\n    original_text: str = Field(\"The original text to be summarized\")\n    items: List[str] = Field(\"A list of summary points\")\n\nllm = Chat(\"claude-3-5-sonnet-latest\", result_type=Summary)\nresponse = llm.send_message_sync(\n    \"summarize the contents of example.com\"\n)\nprint(response.data)\n```\n\nMore examples can be found in the [examples/](https://github.com/dylibso/mcpx-py/tree/main/examples) directory\n\n## Command Line Usage\n\n### Installation\n\n```sh\nuv tool install mcpx-py\n```\n\nFrom git:\n\n```sh\nuv tool install git+https://github.com/dylibso/mcpx-py\n```\n\nOr from the root of the repo:\n\n```sh\nuv tool install .\n```\n\n#### uvx\n\nmcpx-client can also be executed without being installed using `uvx`:\n\n```sh\nuvx --from mcpx-py mcpx-client\n```\n\nOr from git:\n\n```sh\nuvx --from git+https://github.com/dylibso/mcpx-py mcpx-client\n```\n\n### Running\n\n#### Get usage/help\n\n```sh\nmcpx-client --help\n```\n\n#### Chat with an LLM\n\n```sh\nmcpx-client chat\n```\n\n#### List tools\n\n```sh\nmcpx-client list\n```\n\n#### Call a tool\n\n```sh\nmcpx-client tool eval-js '{\"code\": \"2+2\"}'\n```\n\n### LLM Configuration\n\n#### Provider Setup\n\n##### Claude\n1. Sign up for an Anthropic API account at https://console.anthropic.com\n2. Get your API key from the console\n3. Set the environment variable: `ANTHROPIC_API_KEY=your_key_here`\n\n##### OpenAI\n1. Create an OpenAI account at https://platform.openai.com\n2. Generate an API key in your account settings\n3. Set the environment variable: `OPENAI_API_KEY=your_key_here`\n\n##### Gemini\n1. Create an Gemini account at https://aistudio.google.com\n2. Generate an API key in your account settings\n3. Set the environment variable: `GEMINI_API_KEY=your_key_here`\n\n##### Ollama\n1. Install Ollama from https://ollama.ai\n2. Pull your desired model: `ollama pull llama3.2`\n3. No API key needed - runs locally\n\n##### Llamafile\n1. Download a Llamafile model from https://github.com/Mozilla-Ocho/llamafile/releases\n2. Make the file executable: `chmod +x your-model.llamafile`\n3. Run in JSON API mode: `./your-model.llamafile --json-api --host 127.0.0.1 --port 8080`\n4. Use with the OpenAI provider pointing to `http://localhost:8080`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylibso%2Fmcpx-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdylibso%2Fmcpx-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylibso%2Fmcpx-py/lists"}