A complete step-by-step guide to create a local MCP (Model Context Protocol) server from scratch.
- Python 3.12 or higher
uvpackage manager installed (Install uv)
mkdir mcp-local-gen
cd mcp-local-genuv init -p 3.12
uv sync# Install MCP with CLI support
uv add "mcp[cli]"
# Install logging library
uv add loguru
# Install Groq API client (optional - for web search functionality)
uv add groqCreate quick-mcp.py with the following content:
# server.py
from mcp.server.fastmcp import FastMCP
from loguru import logger
from groq import Groq
import os
logger.add("./file.log")
# Create an MCP server
mcp = FastMCP("Demo")
# Add an addition tool
@mcp.tool()
def sum(a: float, b: float) -> float:
"""Add two numbers"""
logger.info(f"Summing {a} and {b}")
return a + b
# Add a dynamic greeting resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
"""Get a personalized greeting"""
logger.info(f"Getting greeting for {name}")
return f"Hello, {name}!"
# Add web search tool using Groq (optional)
@mcp.tool()
def web_search_groq(user_query: str, temperature: float = 0.7, max_tokens: int = 2000, top_p: float = 0.94) -> str:
"""Get response from Groq's compound-beta model for web search queries"""
try:
logger.info(f"Processing web search query: {user_query[:100]}...")
client = Groq(api_key=os.getenv("GROQ_API_KEY", "your-api-key-here"))
completion = client.chat.completions.create(
model="compound-beta",
messages=[{"role": "user", "content": user_query}],
temperature=float(temperature),
max_completion_tokens=int(max_tokens),
top_p=float(top_p),
stream=False,
stop=None,
)
response = completion.choices[0].message.content
logger.info("Successfully generated web search response")
return response
except Exception as e:
logger.error(f"Error in web_search_groq: {str(e)}")
return f"An error occurred: {str(e)}"
if __name__ == "__main__":
logger.info("Starting MCP server...")
# Initialize and run the server
mcp.run(transport='stdio')If using the web search functionality:
# Create .env file
echo "GROQ_API_KEY=your-actual-api-key-here" > .envAdd this configuration to your Claude Desktop settings:
{
"mcp-maths-tools": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/mcp-local-gen/",
"run",
"quick-mcp.py"
]
}
}Note: Replace /path/to/your/mcp-local-gen/ with the actual absolute path to your project directory.
Run the server directly:
uv run quick-mcp.pyOr test with MCP CLI:
uv run --with "mcp[cli]" mcp run quick-mcp.pyThe server should start and you should see:
- Log messages in the console
- A
file.logfile created with detailed logging - The server listening on stdio transport
sum(a: float, b: float)- Adds two numbers with loggingweb_search_groq(user_query: str, ...)- Web search using Groq API
greeting://{name}- Dynamic greeting resource for any name
mcp-local-gen/
├── quick-mcp.py # Main MCP server implementation
├── pyproject.toml # Python project configuration
├── uv.lock # UV lock file
├── file.log # Server logs
├── .env # Environment variables (optional)
└── README.md # This guide
- Import errors: Ensure all dependencies are installed with
uv sync - Path issues: Use absolute paths in Claude Desktop configuration
- API key errors: Set
GROQ_API_KEYenvironment variable if using web search - Permission errors: Ensure the project directory is accessible
# Check dependencies
uv show
# Update dependencies
uv lock
# Reinstall environment
uv sync --reinstall- Customize the tools and resources for your specific needs
- Add error handling and validation
- Implement additional MCP features like prompts
- Deploy to a production environment if needed