PyGithub MCP Server
by AstroMined
- docs
- third-party-docs
Below is a high‐level overview of how to structure and create an MCP server using the Python MCP SDK together with uv and uvx. This guide follows the best practices established in the official repositories.
---
## 1. Project Setup with uvx
Use the uvx CLI to scaffold a new MCP server project. This tool takes care of dependency management and creates the essential project structure automatically. For example, run:
```bash
uvx create-mcp-server
```
You'll be prompted for details (like the project name and description), and upon completion, you’ll get a directory structured as follows:
```
my-server/
├── README.md
├── pyproject.toml
└── src/
└── my_server/
├── __init__.py
├── __main__.py
└── server.py
```
This zero-configuration setup allows you to start coding your MCP server immediately.
citeturn0search0
---
## 2. Structuring Your Server Code
Within the generated `server.py`, you’ll define your MCP server. The Python MCP SDK provides the `FastMCP` class, which simplifies the registration of tools, resources, and prompts via decorators.
Here’s a basic example:
```python
from mcp.server.fastmcp import FastMCP
# Initialize the MCP server with a name
mcp = FastMCP("My MCP Server")
# Define a tool using a decorator
@mcp.tool()
def add(a: int, b: int) -> int:
"""Adds two numbers and returns the result."""
return a + b
# Define a resource for personalized greetings
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
"""Returns a greeting message for the provided name."""
return f"Hello, {name}!"
# Entry point to run the server
if __name__ == "__main__":
mcp.run()
```
In this example:
- The `@mcp.tool()` decorator registers the `add` function as a callable tool.
- The `@mcp.resource()` decorator sets up a resource that can be invoked with a URI like `greeting://Alice`.
For more detailed usage, including prompts and asynchronous tools, refer to the [Python MCP SDK documentation](https://github.com/modelcontextprotocol/python-sdk).
citeturn0search1
---
## 3. Installing Dependencies and Running the Server
After setting up your project:
1. Synchronize your dependencies (uvx handles this automatically):
```bash
uv sync --dev --all-extras
```
2. Run your server:
```bash
uv run my-server
```
This command launches your MCP server, which is now ready to receive tool calls and serve resources.
---
## 4. Advanced Usage
Once your basic server is running, you can expand its capabilities by:
- **Adding Prompts:** Use `@mcp.prompt()` to register templates that help LLMs interact with your server.
- **Lifecycle Management:** For complex deployments, integrate lifecycle hooks (e.g., for initializing database connections) using asynchronous context managers.
- **Integration with Claude Desktop:** Install your server into Claude Desktop with commands like `mcp install server.py` to quickly test in a real LLM environment.
---
## Summary
- **Scaffold Your Project:** Use `uvx create-mcp-server` for a quick start.
- **Define Your Endpoints:** Structure your server with tools and resources using decorators provided by the MCP SDK.
- **Run and Test:** Use `uv sync` and `uv run` to install dependencies and run your server.
- **Expand as Needed:** Incorporate advanced features like prompts, asynchronous tools, and lifecycle management.
This modular, zero-configuration approach lets you focus on building out your MCP server’s functionality rather than on setup details.
---
By following these steps, you’ll have a robust, easily maintainable MCP server built on Python that leverages uv and uvx for streamlined project management and deployment.