How to beginner · 3 min read

How to run MCP server with stdio

Q: How to run MCP server with stdio

Use the official mcp Python SDK to run an MCP server with stdio transport by importing stdio_server from mcp.server.stdio and calling it with your Server instance. This runs the server over standard input/output streams, enabling easy integration with AI agents and tools.

Quick answer

Use the official mcp Python SDK to run an MCP server with stdio transport by importing stdio_server from mcp.server.stdio and calling it with your Server instance. This runs the server over standard input/output streams, enabling easy integration with AI agents and tools.

PREREQUISITES

Python 3.8+
pip install mcp
Basic knowledge of Python async programming

Setup

Install the official MCP Python SDK using pip. This package provides the Server class and the stdio_server helper to run the server over standard input/output.

Run the following command in your terminal:

bash

pip install mcp

Step by step

Create a Python script that defines your MCP Server instance and runs it using the stdio_server function. This example shows a minimal server that echoes received messages.

python

from mcp.server import Server
from mcp.server.stdio import stdio_server

# Define a simple MCP server class
class EchoServer(Server):
    async def handle_message(self, message):
        # Echo back the received message
        return message

# Instantiate the server
server = EchoServer()

# Run the server with stdio transport
stdio_server(server)

Common variations

Async server: The MCP server is inherently async; implement async handlers for concurrency.
Custom handlers: Override handle_message or other methods to add logic.
Other transports: MCP supports SSE transport; use sse_server instead of stdio_server if needed.

Troubleshooting

If the server does not respond, ensure your environment supports stdio communication (e.g., no buffering issues).
Check Python version is 3.8 or higher.
Verify mcp package is installed and up to date.
Use logging inside handle_message to debug message flow.

✅

Key Takeaways

Use the official mcp Python SDK to run MCP servers with stdio transport.
Implement async handle_message methods for custom logic.
Run stdio_server(server) to start the server over standard input/output.
Ensure Python 3.8+ and proper environment for stdio communication.
Use logging and update mcp package to troubleshoot issues.

Verified 2026-04

Verify ↗