mcpeasy 0.1.0

The simplest way to use Model Context Protocol in Python

MCPEasy 🚀

The simplest way to use Model Context Protocol in Python

A high-level, easy-to-use wrapper around the official Anthropic MCP SDK.

Why MCPEasy?

The official MCP SDK is powerful but low-level. MCPEasy makes it dead simple to:

• ✅ Connect to any MCP server with one line of code
• ✅ Call tools without worrying about async complexity
• ✅ Handle subprocess management automatically
• ✅ Get started in seconds, not hours

Installation

pip install mcpeasy

Quick Start

import asyncio
from mcpeasy import connect

async def main():
    # Connect to any MCP server
    client = connect("python -m my_mcp_server")
    
    # List available tools
    tools = await client.list_tools()
    print(f"Available tools: {[t.name for t in tools.tools]}")
    
    # Call a tool
    response = await client.call("my_tool", {"arg": "value"})
    
    if response.success:
        print(response.content)
    else:
        print(f"Error: {response.error}")
    
    # Clean up
    await client.close()

asyncio.run(main())

That's it! 🎉

Comparison: Official SDK vs MCPEasy

Official MCP SDK (Low-level)

from mcp import ClientSession
from mcp.client.stdio import stdio_client, StdioServerParameters

async def use_mcp():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "my_mcp_server"],
        env=os.environ.copy()
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("tool_name", {})
            # ... handle result

MCPEasy (High-level) ✨

from mcpeasy import connect

client = connect("python -m my_mcp_server")
result = await client.call("tool_name", {})

90% less code!

Features

• 🎯 Simple API - Just connect() and call()
• 🔄 Async/Await - Built on Python's asyncio
• 🛠️ Tool Discovery - List all available tools
• 🐛 Error Handling - Clear error messages
• 📦 Process Management - Automatic subprocess handling
• 🔌 Works with ANY MCP server - SQLite, web search, custom servers

Examples

Example 1: SQLite MCP Server

from mcpeasy import connect

# Connect to SQLite MCP server
client = connect("python -m mcp_servers.sqlite_server")

# Get database statistics
response = await client.call("get_memory_stats", {})
print(response.content)

# Run SQL query
response = await client.call("query_memories", {
    "sql": "SELECT * FROM memories WHERE category = 'personal'"
})
print(response.content)

await client.close()

Example 2: Web Search MCP Server

from mcpeasy import connect

# Connect to DuckDuckGo MCP server
client = connect("python -m mcp_servers.duckduckgo_server")

# Search the web
response = await client.call("web_search", {
    "query": "Python programming",
    "count": 5
})
print(response.content)

await client.close()

Example 3: Custom MCP Server

from mcpeasy import connect

# Connect to your custom server
client = connect("python -m my_custom_server")

# List what it can do
tools = await client.list_tools()
for tool in tools.tools:
    print(f"📌 {tool.name}: {tool.description}")

# Call your custom tool
response = await client.call("custom_tool", {"param": "value"})

await client.close()

API Reference

connect(command: str) -> MCPClient

Create an MCP client.

Parameters:

• command (str): Command to start the MCP server (e.g., "python -m my_server")

Returns:

• MCPClient: Ready-to-use client instance

MCPClient.call(tool: str, args: dict) -> MCPResponse

Call a tool on the MCP server.

Parameters:

• tool (str): Name of the tool to call
• args (dict): Arguments to pass to the tool

Returns:

• MCPResponse: Object with .success, .content, and .error attributes

MCPClient.list_tools() -> ListToolsResult

List all available tools.

Returns:

• ListToolsResult: Object with .tools list

MCPClient.close() -> None

Close the client and clean up resources.

Requirements

• Python 3.10+
• Official MCP SDK (mcp package)

Development

# Clone the repository
git clone https://github.com/yourusername/mcpeasy.git
cd mcpeasy

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Build package
python -m build

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built on top of the official Anthropic MCP SDK
• Inspired by the need for simpler MCP tooling

Links

• Documentation: https://github.com/yourusername/mcpeasy
• PyPI: https://pypi.org/project/mcpeasy/
• Issues: https://github.com/yourusername/mcpeasy/issues
• MCP Specification: https://modelcontextprotocol.io/

Star History

If you find this useful, please ⭐ star the repository!

---

Made with ❤️ for the MCP community