Unified MCP Client Library for Elixir

<picture>

</picture>

<h1 align="center">Unified MCP Client Library for Elixir</h1>

🌐 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:

def deps do
  [
    {:mcpixir, "~> 0.1.0"}
  ]
end

Or install from source:

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:

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:

# 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:

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):

{
  "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

# 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

# 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):

{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb"]
    }
  }
}

Blender 3D Creation

# 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:

# 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:

# 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}")

…