Unified MCP Client Library for Elixir

<picture> <img alt="" src="./static/image.png" width="600" style="background: transparent;"> </picture> <h1 align="center">Unified MCP Client Library for Elixir</h1> [](https://github.com/ramonlimaramos/mcpixir/blob/main/LICENSE) [](https://elixir-lang.org/) [](https://hex.pm/packages/mcpixir) [](https://hex.pm/packages/mcpixir) 🌐 Mcpixir is the open source way to connect **any LLM to any MCP server** and build custom agents that have tool access, without using closed source or application clients. 💡 Let developers easily connect any LLM to tools like web browsing, file operations, and more. # Features ## ✨ Key Features | Feature | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------ | | 🔄 **Ease of use** | Create your first MCP capable agent you need only 6 lines of code | | 🤖 **LLM Flexibility** | Works with any LLM that supports tool calling (OpenAI, Anthropic, etc.) | | 🌐 **HTTP Support** | Direct connection to MCP servers running on specific HTTP ports | | ⚙️ **Dynamic Server Selection** | Agents can dynamically choose the most appropriate MCP server for a given task from the available pool | | 🧩 **Multi-Server Support** | Use multiple MCP servers simultaneously in a single agent | | 🛡️ **Tool Restrictions** | Restrict potentially dangerous tools like file system or network access | # Quick start Add `mcpixir` to your list of dependencies in `mix.exs`: ```elixir def deps do [ {:mcpixir, "~> 0.1.0"} ] end ``` Or install from source: ```bash git clone https://github.com/yourusername/mcpixir.git cd mcpixir mix deps.get mix compile ``` ### Configuring LLM Providers Mcpixir works with various LLM providers. You'll need to configure your preferred LLM in your application. Add your API keys for the provider you want to use to your environment variables: ```bash export OPENAI_API_KEY=your_openai_key_here export ANTHROPIC_API_KEY=your_anthropic_key_here ``` > **Important**: Only models with tool calling capabilities can be used with Mcpixir. Make sure your chosen model supports function calling or tool use. ### Spin up your agent: ```elixir # Create configuration dictionary config = %{ mcpServers: %{ playwright: %{ command: "npx", args: ["@playwright/mcp@latest"], env: %{ DISPLAY: ":1" } } } } # Create MCP client from configuration dictionary client = Mcpixir.new_client(config) # Configure LLM llm_config = %{ provider: :openai, model: "gpt-4o" } # Create agent {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client }) # Run the query {:ok, result, updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco") IO.puts("\nResult: #{result}") ``` You can also add the servers configuration from a config file like this: ```elixir config_path = Path.join("path/to", "browser_mcp.json") {:ok, config_data} = File.read(config_path) {:ok, config} = Jason.decode(config_data) client = Mcpixir.new_client(config) ``` Example configuration file (`browser_mcp.json`): ```json { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"], "env": { "DISPLAY": ":1" } } } } ``` For other settings, models, and more, check out the documentation. # Example Use Cases ## Web Browsing with Playwright ```elixir # Create configuration config = %{ mcpServers: %{ playwright: %{ command: "npx", args: ["@playwright/mcp@latest"], env: %{ DISPLAY: ":1" } } } } # Create the MCP client client = Mcpixir.new_client(config) # Configure LLM llm_config = %{ provider: :openai, model: "gpt-4o" # Alternative models: # provider: :anthropic, model: "claude-3-5-sonnet" # provider: :groq, model: "llama3-8b-8192" } # Create agent {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client }) # Run the query {:ok, result, updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco USING GOOGLE SEARCH") IO.puts("\nResult: #{result}") # Ensure we clean up resources properly Mcpixir.Client.stop_all_sessions(client) ``` ## Airbnb Search ```elixir # Create configuration with Airbnb config = %{ mcpServers: %{ airbnb: %{ command: "npx", args: ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"] } } } # Create the MCP client client = Mcpixir.new_client(config) # Configure LLM llm_config = %{ provider: :anthropic, model: "claude-3-5-sonnet" } # Create agent {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client }) # Run a query to search for accommodations query = """ Find me a nice place to stay in Barcelona for 2 adults for a week in August. I prefer places with a pool and good reviews. Show me the top 3 options. """ {:ok, result, updated_agent} = Mcpixir.run(agent, query) IO.puts("\nResult: #{result}") # Ensure we clean up resources properly Mcpixir.Client.stop_all_sessions(client) ``` Example configuration file (`airbnb_mcp.json`): ```json { "mcpServers": { "airbnb": { "command": "npx", "args": ["-y", "@openbnb/mcp-server-airbnb"] } } } ``` ## Blender 3D Creation ```elixir # Create configuration with Blender config = %{ mcpServers: %{ blender: %{ command: "uvx", args: ["blender-mcp"] } } } # Create the MCP client client = Mcpixir.new_client(config) # Configure LLM llm_config = %{ provider: :anthropic, model: "claude-3-5-sonnet" } # Create agent {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client }) # Run the query {:ok, result, updated_agent} = Mcpixir.run(agent, "Create an inflatable cube with soft material and a plane as ground.") IO.puts("\nResult: #{result}") # Ensure we clean up resources properly Mcpixir.Client.stop_all_sessions(client) ``` # Configuration Options MCP-Use supports initialization from configuration files, making it easy to manage and switch between different MCP server setups: ```elixir # Load configuration from file config_path = Path.join("path/to", "mcp-config.json") {:ok, config_data} = File.read(config_path) {:ok, config} = Jason.decode(config_data) # Create an MCP client from config client = Mcpixir.new_client(config) # Create and initialize a session {:ok, client, session} = Mcpixir.Client.create_session(client, "http://localhost:8000") # Use the session... # Disconnect when done Mcpixir.Client.stop_session(client, session.id) ``` ## HTTP Connection Example Mcpixir supports HTTP connections, allowing you to connect to MCP servers running on specific HTTP ports. This feature is particularly useful for integrating with web-based MCP servers. Here's an example of how to use the HTTP connection feature: ```elixir # Configuration with HTTP connection config = %{ mcpServers: %{ http: %{ url: "http://localhost:8931/sse" } } } # Create the MCP client client = Mcpixir.new_client(config) # Configure LLM llm_config = %{ provider: :openai, model: "gpt-4o" } # Create agent {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client }) # Run the query {:ok, result, updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco USING GOOGLE SEARCH") IO.puts("\nResult: #{result}") ``` This example demonstrates how to connect to an MCP server running on a specific HTTP port. Make sure to start your MCP server before running this example. # Multi-Server Support Mcpixir allows configuring and connecting to multiple MCP servers simultaneously using the `Mcpixir.Client`. This enables complex workflows that require tools from different servers, such as web browsing combined with file operations or 3D modeling. ## Configuration You can configure multiple servers in your configuration file: ```json { "mcpServers": { "airbnb": { "command": "npx", "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"] }, "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"], "env": { "DISPLAY": ":1" } } } } ``` ## Usage The `Mcpixir.Client` module provides functions for managing connections to multiple servers. When creating an agent, you can provide a client configured with multiple servers. By default, the agent will have access to tools from all configured servers. If you need to target a specific server for a particular task, you can specify the server parameters when creating the agent. ```elixir # Create client with multiple servers config = load_multi_server_config() client = Mcpixir.new_client(config) # Example: Running a query that may use tools from both servers {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client }) # Query combining different capabilities query = """ Search for a nice place to stay in Barcelona on Airbnb, then use Google to find nearby restaurants and attractions. """ {:ok, result, _updated_agent} = Mcpixir.run(agent, query) ``` ## Dynamic Server Selection (Server Manager) For enhanced efficiency and to reduce potential agent confusion when dealing with many tools from different servers, you can leverage the built-in server manager functionality. When enabled, the agent intelligently selects the correct MCP server based on the tool chosen by the LLM for a specific step. This minimizes unnecessary connections and ensures the agent uses the appropriate tools for the task. ```elixir # Create client with multiple servers config = load_multi_server_config() client = Mcpixir.new_client(config) # Create agent with server manager enabled {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client, use_server_manager: true # Enable the Server Manager }) # Run a query that uses tools from multiple servers {:ok, result, _updated_agent} = Mcpixir.run(agent, """ Search for a nice place to stay in Barcelona on Airbnb, then use Google to find nearby restaurants and attractions. """) ``` # Tool Access Control MCP-Use allows you to restrict which tools are available to the agent, providing better security and control over agent capabilities: ```elixir # Create client config = load_config() client = Mcpixir.new_client(config) # Create agent with restricted tools {:ok, agent} = Mcpixir.new_agent(%{ llm: llm_config, client: client, disallowed_tools: ["file_system", "network"] # Restrict potentially dangerous tools }) # Run a query with restricted tool access {:ok, result, _updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco") ``` # Running Examples We provide a set of Mix tasks for demonstrating different aspects of the library. These tasks use real LLMs and MCP servers to showcase the full functionality. ## Mix Tasks Run `mix mcp` to see all available examples: ```bash mix mcpixir ``` Available examples: - `mix mcpixir.chat` - Simple chat interaction with tools - `mix mcpixir.airbnb` - Example showing integration with Airbnb - `mix mcpixir.blender` - Example for controlling Blender 3D software - `mix mcpixir.browser` - Web browsing with Playwright - `mix mcpixir.filesystem` - Working with the filesystem - `mix mcpixir.http` - HTTP connection to MCP servers - `mix mcpixir.multi` - Using multiple MCP servers together To get help on a specific example: ```bash mix help mcpixir.chat ``` ## Running Examples Each example can be run with the following pattern: ```bash # Basic usage mix mcpixir.chat # With options mix mcpixir.browser --provider=anthropic --query="Find the top 5 Elixir packages on Hex.pm" ``` ## Common Options Most examples support these common options: - `--provider=[openai|anthropic]` - LLM provider to use - `--model=MODEL` - Specific LLM model to use - `--query=QUERY` - The query to send to the LLM ## API Keys These examples require API keys for OpenAI or Anthropic. Set them in your environment: ```bash # For OpenAI export OPENAI_API_KEY=your-openai-key # For Anthropic export ANTHROPIC_API_KEY=your-anthropic-key ``` # Debugging Mcpixir provides built-in logging that helps diagnose issues in your agent implementation. ## Configuring Logging There are several ways to configure logging: ### 1. Environment Variable Set the log level using the `MCP_USE_LOG_LEVEL` environment variable: ```bash export MCP_USE_LOG_LEVEL=debug # Options: debug, info, warn, error ``` ### 2. Setting Log Level Programmatically You can set the log level directly in your code: ```elixir # Set global log level Mcpixir.Logging.set_level(:debug) # Options: :debug, :info, :warning, :error ``` ### 3. Configuration in mix.exs or config.exs ```elixir # In config/config.exs config :mcpixir, log_level: :debug ``` # Roadmap - [x] Multiple Servers at once - [x] Test remote connectors (http, ws) - [ ] ... # Contributing We love contributions! Feel free to open issues for bugs or feature requests. # Requirements - Elixir 1.15+ - Erlang/OTP 25+ - MCP implementation (like Playwright MCP) - LLM API access (OpenAI, Anthropic, etc.) # Contributing ## Development Process We welcome contributions to make this project better! Here are some steps to get started: ```bash # Clone the repository git clone https://github.com/yourusername/mcp-use-elixir.git cd mcp-use-elixir # Install dependencies mix deps.get # Run tests mix test # Run the code formatter mix format # Run the linter mix credo ``` ## Release Process This project follows semantic versioning and uses a structured release process. You can release a new version using either: ### Using the Mix task ```bash mix mcp.release 0.2.0 ``` ### Using the shell script ```bash ./bin/release.sh 0.2.0 ``` Both methods will: 1. Check if the working directory is clean 2. Update the version in mix.exs 3. Update the CHANGELOG.md with the new version 4. Run tests to ensure everything works 5. Compile documentation 6. Create a git commit and tag 7. Publish to Hex.pm # License MIT