https://github.com/dylibso/mcpx-py
Python client library for https://mcp.run - call portable & secure tools for your AI Agents and Apps
https://github.com/dylibso/mcpx-py
agents ai llm mcp mcp-client mcp-run mcp-server python
Last synced: about 1 year ago
JSON representation
Python client library for https://mcp.run - call portable & secure tools for your AI Agents and Apps
- Host: GitHub
- URL: https://github.com/dylibso/mcpx-py
- Owner: dylibso
- License: bsd-3-clause
- Created: 2024-12-04T22:21:56.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-20T18:02:08.000Z (over 1 year ago)
- Last Synced: 2025-03-27T08:11:37.842Z (over 1 year ago)
- Topics: agents, ai, llm, mcp, mcp-client, mcp-run, mcp-server, python
- Language: Python
- Homepage: https://docs.mcp.run
- Size: 582 KB
- Stars: 11
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mcpx-py
[](https://pypi.org/project/mcpx-py/)
A Python library for interacting with LLMs using mcp.run tools
## Features
### AI Provider Support
`mcpx-py` supports all models supported by [PydanticAI](https://ai.pydantic.dev/models/)
## Dependencies
- `uv`
- `npm`
- `ollama` (optional)
## mcp.run Setup
You will need to get an mcp.run session ID by running:
```bash
npx --yes -p @dylibso/mcpx gen-session --write
```
This will generate a new session and write the session ID to a configuration file that can be used
by `mcpx-py`.
If you need to store the session ID in an environment variable you can run `gen-session`
without the `--write` flag:
```bash
npx --yes -p @dylibso/mcpx gen-session
```
which should output something like:
```
Login successful!
Session: kabA7w6qH58H7kKOQ5su4v3bX_CeFn4k.Y4l/s/9dQwkjv9r8t/xZFjsn2fkLzf+tkve89P1vKhQ
```
Then set the `MPC_RUN_SESSION_ID` environment variable:
```
$ export MCP_RUN_SESSION_ID=kabA7w6qH58H7kKOQ5su4v3bX_CeFn4k.Y4l/s/9dQwkjv9r8t/xZFjsn2fkLzf+tkve89P1vKhQ
```
## Python Usage
### Installation
Using `uv`:
```bash
uv add mcpx-py
```
Or `pip`:
```bash
pip install mcpx-py
```
### Example code
```python
from mcpx_py import Chat
llm = Chat("claude-3-5-sonnet-latest")
# Or OpenAI
# llm = Chat("gpt-4o")
# Or Ollama
# llm = Chat("ollama:qwen2.5")
# Or Gemini
# llm = Chat("gemini-2.0-flash")
response = llm.send_message_sync(
"summarize the contents of example.com"
)
print(response.data)
```
It's also possible to get structured output by setting `result_type`
```python
from mcpx_py import Chat, BaseModel, Field
from typing import List
class Summary(BaseModel):
"""
A summary of some longer text
"""
source: str = Field("The source of the original_text")
original_text: str = Field("The original text to be summarized")
items: List[str] = Field("A list of summary points")
llm = Chat("claude-3-5-sonnet-latest", result_type=Summary)
response = llm.send_message_sync(
"summarize the contents of example.com"
)
print(response.data)
```
More examples can be found in the [examples/](https://github.com/dylibso/mcpx-py/tree/main/examples) directory
## Command Line Usage
### Installation
```sh
uv tool install mcpx-py
```
From git:
```sh
uv tool install git+https://github.com/dylibso/mcpx-py
```
Or from the root of the repo:
```sh
uv tool install .
```
#### uvx
mcpx-client can also be executed without being installed using `uvx`:
```sh
uvx --from mcpx-py mcpx-client
```
Or from git:
```sh
uvx --from git+https://github.com/dylibso/mcpx-py mcpx-client
```
### Running
#### Get usage/help
```sh
mcpx-client --help
```
#### Chat with an LLM
```sh
mcpx-client chat
```
#### List tools
```sh
mcpx-client list
```
#### Call a tool
```sh
mcpx-client tool eval-js '{"code": "2+2"}'
```
### LLM Configuration
#### Provider Setup
##### Claude
1. Sign up for an Anthropic API account at https://console.anthropic.com
2. Get your API key from the console
3. Set the environment variable: `ANTHROPIC_API_KEY=your_key_here`
##### OpenAI
1. Create an OpenAI account at https://platform.openai.com
2. Generate an API key in your account settings
3. Set the environment variable: `OPENAI_API_KEY=your_key_here`
##### Gemini
1. Create an Gemini account at https://aistudio.google.com
2. Generate an API key in your account settings
3. Set the environment variable: `GEMINI_API_KEY=your_key_here`
##### Ollama
1. Install Ollama from https://ollama.ai
2. Pull your desired model: `ollama pull llama3.2`
3. No API key needed - runs locally
##### Llamafile
1. Download a Llamafile model from https://github.com/Mozilla-Ocho/llamafile/releases
2. Make the file executable: `chmod +x your-model.llamafile`
3. Run in JSON API mode: `./your-model.llamafile --json-api --host 127.0.0.1 --port 8080`
4. Use with the OpenAI provider pointing to `http://localhost:8080`