# aiohttp-mcp
[](https://codecov.io/gh/kulapard/aiohttp-mcp)
[](https://results.pre-commit.ci/latest/github/kulapard/aiohttp-mcp/master)
[](https://pypi.org/project/aiohttp-mcp)
[](https://pepy.tech/projects/aiohttp-mcp)
---
Tools for building [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers on top of [aiohttp](https://docs.aiohttp.org/).
## Features
- Easy integration with aiohttp web applications
- Support for Model Context Protocol (MCP) tools
- Async-first design
- Type hints support
- Debug mode for development
- Flexible routing options
## Installation
With [uv](https://docs.astral.sh/uv/) package manager:
```bash
uv add aiohttp-mcp
```
Or with pip:
```bash
pip install aiohttp-mcp
```
## Quick Start
### Basic Server Setup
Create a simple MCP server with a custom tool:
```python
import datetime
from zoneinfo import ZoneInfo
from aiohttp import web
from aiohttp_mcp import AiohttpMCP, build_mcp_app
# Initialize MCP
mcp = AiohttpMCP()
# Define a tool
@mcp.tool()
def get_time(timezone: str) -> str:
"""Get the current time in the specified timezone."""
tz = ZoneInfo(timezone)
return datetime.datetime.now(tz).isoformat()
# Create and run the application
app = build_mcp_app(mcp, path="/mcp")
web.run_app(app)
```
### Using as a Sub-Application
You can also use aiohttp-mcp as a sub-application in your existing aiohttp server:
```python
import datetime
from zoneinfo import ZoneInfo
from aiohttp import web
from aiohttp_mcp import AiohttpMCP, setup_mcp_subapp
mcp = AiohttpMCP()
# Define a tool
@mcp.tool()
def get_time(timezone: str) -> str:
"""Get the current time in the specified timezone."""
tz = ZoneInfo(timezone)
return datetime.datetime.now(tz).isoformat()
# Create your main application
app = web.Application()
# Add MCP as a sub-application
setup_mcp_subapp(app, mcp, prefix="/mcp")
web.run_app(app)
```
### Using Streamable HTTP Transport
For production deployments requiring advanced session management, you can use the streamable HTTP transport mode:
```python
import datetime
from zoneinfo import ZoneInfo
from aiohttp import web
from aiohttp_mcp import AiohttpMCP, TransportMode, build_mcp_app
# Initialize MCP
mcp = AiohttpMCP()
# Define a tool
@mcp.tool()
def get_time(timezone: str) -> str:
"""Get the current time in the specified timezone."""
tz = ZoneInfo(timezone)
return datetime.datetime.now(tz).isoformat()
# Create application with streamable transport
app = build_mcp_app(mcp, path="/mcp", transport_mode=TransportMode.STREAMABLE_HTTP, stateless=True)
web.run_app(app)
```
### Client Example
Here's how to create a client that interacts with the MCP server:
```python
import asyncio
from mcp import ClientSession
from mcp.client.sse import sse_client
async def main():
# Connect to the MCP server
async with sse_client("http://localhost:8080/mcp") as (read_stream, write_stream):
async with ClientSession(read_stream, write_stream) as session:
# Initialize the session
await session.initialize()
# List available tools
tools = await session.list_tools()
print("Available tools:", [tool.name for tool in tools.tools])
# Call a tool
result = await session.call_tool("get_time", {"timezone": "UTC"})
print("Current time in UTC:", result.content)
if __name__ == "__main__":
asyncio.run(main())
```
### More Examples
For more examples, check the [examples](examples) directory.
## Development
### Setup Development Environment
1. Clone the repository:
```bash
git clone https://github.com/kulapard/aiohttp-mcp.git
cd aiohttp-mcp
```
2. Create and activate a virtual environment:
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. Install development dependencies:
```bash
uv sync --all-extras
```
### Running Tests
```bash
uv run pytest
```
## Requirements
- Python 3.10 or higher
- aiohttp >= 3.9.0, < 4.0.0
- aiohttp-sse >= 2.2.0, < 3.0.0
- anyio >= 4.9.0, < 5.0.0
- mcp >= 1.8.0, < 2.0.0
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "aiohttp-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, aiohttp, async, llm, mcp, model-context-protocol, server",
"author": null,
"author_email": "Taras Drapalyuk <taras@drapalyuk.com>",
"download_url": "https://files.pythonhosted.org/packages/47/5e/8db62b976d3b5ea3047e6080f6f435221353b0439e72935d5f1ecc6e481e/aiohttp_mcp-0.6.0.tar.gz",
"platform": null,
"description": "# aiohttp-mcp\n\n\n[](https://codecov.io/gh/kulapard/aiohttp-mcp)\n[](https://results.pre-commit.ci/latest/github/kulapard/aiohttp-mcp/master)\n[](https://pypi.org/project/aiohttp-mcp)\n[](https://pepy.tech/projects/aiohttp-mcp)\n\n\n---\n\nTools for building [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers on top of [aiohttp](https://docs.aiohttp.org/).\n\n## Features\n\n- Easy integration with aiohttp web applications\n- Support for Model Context Protocol (MCP) tools\n- Async-first design\n- Type hints support\n- Debug mode for development\n- Flexible routing options\n\n## Installation\n\nWith [uv](https://docs.astral.sh/uv/) package manager:\n\n```bash\nuv add aiohttp-mcp\n```\n\nOr with pip:\n\n```bash\npip install aiohttp-mcp\n```\n\n## Quick Start\n\n### Basic Server Setup\n\nCreate a simple MCP server with a custom tool:\n\n```python\nimport datetime\nfrom zoneinfo import ZoneInfo\n\nfrom aiohttp import web\n\nfrom aiohttp_mcp import AiohttpMCP, build_mcp_app\n\n# Initialize MCP\nmcp = AiohttpMCP()\n\n\n# Define a tool\n@mcp.tool()\ndef get_time(timezone: str) -> str:\n \"\"\"Get the current time in the specified timezone.\"\"\"\n tz = ZoneInfo(timezone)\n return datetime.datetime.now(tz).isoformat()\n\n\n# Create and run the application\napp = build_mcp_app(mcp, path=\"/mcp\")\nweb.run_app(app)\n```\n\n### Using as a Sub-Application\n\nYou can also use aiohttp-mcp as a sub-application in your existing aiohttp server:\n\n```python\nimport datetime\nfrom zoneinfo import ZoneInfo\n\nfrom aiohttp import web\n\nfrom aiohttp_mcp import AiohttpMCP, setup_mcp_subapp\n\nmcp = AiohttpMCP()\n\n\n# Define a tool\n@mcp.tool()\ndef get_time(timezone: str) -> str:\n \"\"\"Get the current time in the specified timezone.\"\"\"\n tz = ZoneInfo(timezone)\n return datetime.datetime.now(tz).isoformat()\n\n\n# Create your main application\napp = web.Application()\n\n# Add MCP as a sub-application\nsetup_mcp_subapp(app, mcp, prefix=\"/mcp\")\n\nweb.run_app(app)\n```\n\n### Using Streamable HTTP Transport\n\nFor production deployments requiring advanced session management, you can use the streamable HTTP transport mode:\n\n```python\nimport datetime\nfrom zoneinfo import ZoneInfo\n\nfrom aiohttp import web\n\nfrom aiohttp_mcp import AiohttpMCP, TransportMode, build_mcp_app\n\n# Initialize MCP\nmcp = AiohttpMCP()\n\n\n# Define a tool\n@mcp.tool()\ndef get_time(timezone: str) -> str:\n \"\"\"Get the current time in the specified timezone.\"\"\"\n tz = ZoneInfo(timezone)\n return datetime.datetime.now(tz).isoformat()\n\n\n# Create application with streamable transport\napp = build_mcp_app(mcp, path=\"/mcp\", transport_mode=TransportMode.STREAMABLE_HTTP, stateless=True)\nweb.run_app(app)\n```\n\n### Client Example\n\nHere's how to create a client that interacts with the MCP server:\n\n```python\nimport asyncio\n\nfrom mcp import ClientSession\nfrom mcp.client.sse import sse_client\n\n\nasync def main():\n # Connect to the MCP server\n async with sse_client(\"http://localhost:8080/mcp\") as (read_stream, write_stream):\n async with ClientSession(read_stream, write_stream) as session:\n # Initialize the session\n await session.initialize()\n\n # List available tools\n tools = await session.list_tools()\n print(\"Available tools:\", [tool.name for tool in tools.tools])\n\n # Call a tool\n result = await session.call_tool(\"get_time\", {\"timezone\": \"UTC\"})\n print(\"Current time in UTC:\", result.content)\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### More Examples\n\nFor more examples, check the [examples](examples) directory.\n\n## Development\n\n### Setup Development Environment\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/kulapard/aiohttp-mcp.git\ncd aiohttp-mcp\n```\n\n2. Create and activate a virtual environment:\n\n```bash\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n```\n\n3. Install development dependencies:\n\n```bash\nuv sync --all-extras\n```\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n## Requirements\n\n- Python 3.10 or higher\n- aiohttp >= 3.9.0, < 4.0.0\n- aiohttp-sse >= 2.2.0, < 3.0.0\n- anyio >= 4.9.0, < 5.0.0\n- mcp >= 1.8.0, < 2.0.0\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tools for building Model Context Protocol (MCP) servers on top of aiohttp",
"version": "0.6.0",
"project_urls": {
"Documentation": "https://github.com/kulapard/aiohttp-mcp#readme",
"Homepage": "https://github.com/kulapard/aiohttp-mcp",
"Repository": "https://github.com/kulapard/aiohttp-mcp.git"
},
"split_keywords": [
"ai",
" aiohttp",
" async",
" llm",
" mcp",
" model-context-protocol",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "51f2d5a5a41551317a51d330352e2df43fc3811f22c4862027476effaa24f6da",
"md5": "d3aa1f207281d962e7fc89979d292bd7",
"sha256": "5dd50765a1c697c75cc3af201c70ae5c03a0762dfb53d12acb627cb5be493987"
},
"downloads": -1,
"filename": "aiohttp_mcp-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3aa1f207281d962e7fc89979d292bd7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25003,
"upload_time": "2025-11-03T19:25:03",
"upload_time_iso_8601": "2025-11-03T19:25:03.251699Z",
"url": "https://files.pythonhosted.org/packages/51/f2/d5a5a41551317a51d330352e2df43fc3811f22c4862027476effaa24f6da/aiohttp_mcp-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "475e8db62b976d3b5ea3047e6080f6f435221353b0439e72935d5f1ecc6e481e",
"md5": "f96518a8f36bf2ec9faa83e04335711a",
"sha256": "2e37627e5e16df11757ff79f80beab9db97dd083d8d157b30fcb08c7590d9096"
},
"downloads": -1,
"filename": "aiohttp_mcp-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "f96518a8f36bf2ec9faa83e04335711a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22145,
"upload_time": "2025-11-03T19:25:04",
"upload_time_iso_8601": "2025-11-03T19:25:04.646264Z",
"url": "https://files.pythonhosted.org/packages/47/5e/8db62b976d3b5ea3047e6080f6f435221353b0439e72935d5f1ecc6e481e/aiohttp_mcp-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 19:25:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kulapard",
"github_project": "aiohttp-mcp#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiohttp-mcp"
}
JSON
