📌Overview

Purpose: The MCP Plugin for ElizaOS aims to integrate the Model Context Protocol (MCP) with ElizaOS, enabling agents to connect to multiple MCP servers for enhanced operations.

Overview: This plugin facilitates the seamless integration of various MCP servers, providing ElizaOS agents access to diverse resources, prompts, and tools necessary for effective interaction and functionality.

Key Features:

Multiple MCP Server Support: Allows agents to simultaneously connect to various MCP servers, enhancing their capabilities with different resources and tools for improved performance.
Flexible Configuration Options: Offers customizable server options, including types (stdio and sse) and parameters (such as timeout and environment variables) tailored for specific requirements.

MCP Plugin for ElizaOS

This plugin integrates the Model Context Protocol (MCP) with ElizaOS, allowing agents to connect to multiple MCP servers and use their resources, prompts, and tools.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. It provides a standardized way to connect LLMs with the context they need.

This plugin allows your ElizaOS agents to access multiple MCP servers simultaneously, each providing different capabilities:

Resources: Context and data for the agent to reference
Prompts: Templated messages and workflows
Tools: Functions for the agent to execute

Installation

Install the plugin in your ElizaOS project using one of the following:

npm

npm install @fleek-platform/eliza-plugin-mcp

pnpm

pnpm install @fleek-platform/eliza-plugin-mcp

yarn

yarn add @fleek-platform/eliza-plugin-mcp

bun

bun add @fleek-platform/eliza-plugin-mcp

Usage

Add the plugin to your character configuration:

{
  "name": "Your Character",
  "plugins": ["@fleek-platform/eliza-plugin-mcp"],
  "settings": {
    "mcp": {
      "servers": {
        "github": {
          "type": "stdio",
          "name": "Code Server",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"]
        }
      }
    }
  }
}

Configuration Options

MCP supports two types of servers: "stdio" and "sse". Each type has its own configuration options.

Common Options

Option	Type	Description
`type`	string	The type of MCP server: "stdio" or "sse"
`name`	string	The display name of the server
`timeout`	number	Timeout in seconds for tool calls (default: 60)
`disabled`	boolean	Whether the server is disabled

stdio Server Options

Option	Type	Description
`command`	string	The command to run the MCP server
`args`	string[]	Command-line arguments for the server
`env`	object	Environment variables to pass to the server
`cwd`	string	Optional Working directory to run the server in

sse Server Options

Option	Type	Description
`url`	string	The URL of the SSE endpoint

Using MCP Capabilities

Once configured, the plugin automatically exposes MCP servers' capabilities to your agent:

Context Providers

The plugin includes three providers that add MCP capabilities to the agent's context:

MCP_SERVERS: Lists available servers and their tools, resources and prompts

Plugin Flow

The following diagram illustrates the MCP plugin's flow for tool selection and execution:

graph TD
    start[User Request] --> action[CALL_TOOL Action]
    action --> check{MCP Servers Available?}
    check -->|No| fail[Return No Tools Available]
    check -->|Yes| state[Get MCP Provider Data]
    state --> prompt[Create Tool Selection Prompt]
    prompt --> model1[Use Language Model for Tool Selection]
    model1 --> parse[Parse Selection]
    parse --> retry{Valid Selection?}
    retry -->|No| feedback[Generate Feedback]
    feedback --> model2[Use Language Model for Retry]
    model2 --> parse
    retry -->|Yes| toolAvailable{Tool Available?}
    toolAvailable -->|No| fallback[Fallback Response]
    toolAvailable -->|Yes| callTool[Call MCP Tool]
    callTool --> processResult[Process Tool Result]
    processResult --> createMemory[Create Memory Record]
    createMemory --> reasoningPrompt[Create Reasoning Prompt]
    reasoningPrompt --> model3[Use Language Model for Response]
    model3 --> respondToUser[Send Response to User]

    classDef model fill:#f9f,stroke:#333,stroke-width:2px;
    classDef decision fill:#bbf,stroke:#333,stroke-width:2px;
    classDef output fill:#bfb,stroke:#333,stroke-width:2px;

    class model1,model2,model3 model;
    class check,retry,toolAvailable decision;
    class respondToUser,fallback output;

Example: Setting Up Multiple MCP Servers

Example configuration with multiple MCP servers of both types:

{
  "name": "Developer Assistant",
  "plugins": ["@elizaos/plugin-mcp", "other-plugins"],
  "settings": {
    "mcp": {
      "servers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
          }
        },
        "puppeteer": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
        },
        "google-maps": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-google-maps"],
          "env": {
            "GOOGLE_MAPS_API_KEY": "<YOUR_API_KEY>"
          }
        }
      },
      "maxRetries": 2
    }
  }
}

Security Considerations

MCP servers can execute arbitrary code, so only connect to servers you trust.

Troubleshooting

If you encounter issues with the MCP plugin:

Check that your MCP servers are correctly configured and running.
Ensure the commands are accessible in the ElizaOS environment.
Review the logs for connection errors.
Verify that the plugin is properly loaded in your character configuration.

Contributing

Thanks for considering contributing to our project!

How to Contribute

Fork the repository.
Create a new branch: git checkout -b feature-branch-name.
Make your changes.
Commit your changes using conventional commits.
Push to your fork and submit a pull request.

Commit Guidelines

We use Conventional Commits for our commit messages:

test: 💍 Adding missing tests
feat: 🎸 A new feature
fix: 🐛 A bug fix
chore: 🤖 Build process or auxiliary tool changes
docs: ✏️ Documentation only changes
refactor: 💡 A code change that neither fixes a bug or adds a feature
style: 💄 Markup, white-space, formatting, missing semi-colons...

License

This plugin is released under the same license as ElizaOS.