ExMCP

[![Hex.pm](https://img.shields.io/hexpm/v/ex_mcp.svg)](https://hex.pm/packages/ex_mcp) [![Documentation](https://img.shields.io/badge/docs-hexdocs-blue.svg)](https://hexdocs.pm/ex_mcp) [![CI](https://github.com/azmaveth/ex_mcp/workflows/CI/badge.svg)](https://github.com/azmaveth/ex_mcp/actions) [![Coverage](https://img.shields.io/codecov/c/github/azmaveth/ex_mcp.svg)](https://codecov.io/gh/azmaveth/ex_mcp) [![License](https://img.shields.io/hexpm/l/ex_mcp.svg)](LICENSE) **A complete Elixir implementation of the Model Context Protocol (MCP)** [Getting Started](docs/getting-started/) | [User Guide](docs/guides/USER_GUIDE.md) | [API Docs](https://hexdocs.pm/ex_mcp) | [Examples](examples/) | [Changelog](CHANGELOG.md)

โœ… Production Ready: ExMCP v0.7.0 is production-ready with 100% MCP compliance and comprehensive testing. The API is stable and ready for production use.

Overview

ExMCP is a comprehensive Elixir implementation of the Model Context Protocol, enabling AI models to securely interact with local and remote resources through a standardized protocol. It provides both client and server implementations with multiple transport options, including native Phoenix integration via Plug compatibility.

โœจ Key Features

Protocol & Standards

Performance & Reliability

Integration & Flexibility

Developer Experience

๐Ÿ“ฆ Installation

Add ex_mcp to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_mcp, "~> 0.7.0"}
  ]
end

Then run:

mix deps.get

๐Ÿš€ Quick Start

Phoenix Integration (Recommended)

Add MCP server capabilities to your Phoenix app:

# In your Phoenix router (lib/my_app_web/router.ex)
defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  
  pipeline :mcp do
    plug :accepts, ["json"]
    # Add your authentication/authorization here
  end
  
  scope "/api/mcp" do
    pipe_through :mcp
    
    # Mount MCP server at /api/mcp
    forward "/", ExMCP.HttpPlug,
      handler: MyApp.MCPHandler,
      server_info: %{name: "my-phoenix-app", version: "1.0.0"},
      sse_enabled: true,
      cors_enabled: true
  end
end

# Create your MCP handler (lib/my_app/mcp_handler.ex)
defmodule MyApp.MCPHandler do
  use ExMCP.Server.Handler
  
  @impl true
  def init(_args), do: {:ok, %{}}
  
  @impl true
  def handle_initialize(_params, state) do
    {:ok, %{
      name: "my-phoenix-app",
      version: "1.0.0",
      capabilities: %{tools: %{}, resources: %{}}
    }, state}
  end
  
  @impl true
  def handle_list_tools(state) do
    tools = [
      %{
        name: "get_user_count",
        description: "Get total number of users",
        input_schema: %{type: "object", properties: %{}}
      }
    ]
    {:ok, tools, state}
  end
  
  @impl true
  def handle_call_tool("get_user_count", _args, state) do
    count = MyApp.Accounts.count_users()
    {:ok, [%{type: "text", text: "Total users: #{count}"}], state}
  end
end

Connect from any MCP client:

mcp connect http://localhost:4000/api/mcp

DSL Server (Quickest Way)

Define tools, resources, and prompts declaratively:

defmodule MyServer do
  use ExMCP.Server

  deftool "greet" do
    description "Greets a person by name"
    args do
      field :name, :string, required: true, description: "Person to greet"
    end
  end

  defresource "info://about" do
    name "About"
    description "Server information"
    mime_type "text/plain"
  end

  @impl true
  def handle_tool_call("greet", %{"name" => name}, state) do
    {:ok, %{content: [text("Hello, #{name}!")]}, state}
  end

  @impl true
  def handle_resource_read("info://about", _uri, state) do
    {:ok, [text("MyServer v1.0")], state}
  end
end

See the DSL Guide and examples/ for more patterns.

Standalone MCP Client

# Connect to a stdio-based server
{:ok, client} = ExMCP.Client.start_link(
  transport: :stdio,
  command: ["node", "my-mcp-server.js"]
)

# List available tools
{:ok, tools} = ExMCP.Client.list_tools(client)

# Call a tool
{:ok, result} = ExMCP.Client.call_tool(client, "search", %{
  query: "Elixir programming",
  limit: 10
})

Ultra-Fast Native BEAM Services

For trusted Elixir clusters, use the native BEAM transport:

# Create a service using the ExMCP.Service macro
defmodule MyToolService do
  use ExMCP.Service, name: :my_tools

  @impl true
  def handle_mcp_request("list_tools", _params, state) do
    tools = [
      %{
        "name" => "ping",
        "description" => "Test tool",
        "inputSchema" => %{"type" => "object", "properties" => %{}}
      }
    ]
    {:ok, %{"tools" => tools}, state}
  end

  @impl true
  def handle_mcp_request("tools/call", %{"name" => "ping"}, state) do
    {:ok, %{"content" => [%{"type" => "text", "text" => "Pong!"}]}, state}
  end
end

# Start your service (automatically registers with ExMCP.Native)
{:ok, _} = MyToolService.start_link()

# Direct service calls (~15ฮผs latency)
{:ok, tools} = ExMCP.Native.call(:my_tools, "list_tools", %{})

๐Ÿ“š Documentation

ExMCP provides comprehensive documentation organized for different needs:

๐Ÿš€ Getting Started

๐Ÿ“– Comprehensive Guides

๐Ÿ”ง Development & API

๐Ÿ“‹ Protocol & Specifications

๐ŸŽฏ Transport Performance

Transport Latency Best For Use Case
Native BEAM ~15ฮผs Internal services Elixir cluster communication
stdio ~1-5ms External tools Subprocess communication
HTTP/SSE ~5-20ms Network clients Web applications, remote APIs

โœจ What's New in v0.7.0

See the CHANGELOG for complete details and breaking changes.

๐Ÿค Contributing

We welcome contributions! Please see:

Before contributing:

  1. Fork the repository
  2. Create a feature branch
  3. Run make quality to ensure code quality
  4. Submit a pull request

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ™ Acknowledgments

Made with โค๏ธ for the Elixir community