Spec3 MCP Server
A Model Context Protocol (MCP) server built with FastMCP for local development and testing with Claude Desktop on WSL.
Overview
This MCP server provides a set of tools and utilities that can be used by Claude Desktop through the MCP protocol. It's designed to run locally on your WSL machine and connect to Claude Desktop via stdio.
Features
Modern Python Project Structure: Uses
pyproject.toml
and follows Python packaging best practicesFastMCP Integration: Built on the FastMCP framework for easy MCP protocol handling
Multiple Tools: Includes basic demonstration and utility tools
Comprehensive Logging: Detailed logging for debugging and monitoring
Type Hints: Full type annotation support for better development experience
WSL Compatible: Runs seamlessly on WSL and connects to Claude Desktop
Available Tools
hello_world: Returns a simple greeting message
echo_message: Echoes back a message with additional formatting
get_server_info: Returns comprehensive server information and capabilities
list_available_tools: Lists all available tools with descriptions
Installation
Prerequisites
Python 3.10 or higher
WSL (Windows Subsystem for Linux)
Claude Desktop (installed on Windows)
Setup
Navigate to the project directory:
cd /home/dhevb/workspaces/spec3-mcp-serverCreate and activate a virtual environment:
python -m venv venv source venv/bin/activateInstall the package in development mode:
pip install -e .This will install the package and all its dependencies, including FastMCP.
Verify the installation:
spec3-mcp-server --help
Connecting to Claude Desktop
Configure Claude Desktop on Windows
Locate your Claude Desktop config file:
On Windows, it's typically at:
%APPDATA%\Claude\claude_desktop_config.json
Full path is usually:
C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
Edit the configuration file and add the following:
{ "mcpServers": { "spec3-mcp-server": { "command": "wsl", "args": [ "-e", "/home/dhevb/workspaces/spec3-mcp-server/venv/bin/python", "/home/dhevb/workspaces/spec3-mcp-server/src/spec3_mcp_server/main.py" ], "env": {} } } }Note: The
wsl
command allows Claude Desktop on Windows to execute Python in your WSL environment.Restart Claude Desktop to load the new configuration
Verify the connection:
Open Claude Desktop
Start a new conversation
Look for the MCP tools icon or hammer icon
You should see the spec3-mcp-server tools available
Alternative: Using Installed Command
If you prefer to use the installed spec3-mcp-server
command:
Testing the Server
Test Locally (Without Claude Desktop)
You can test the server locally to ensure it's working:
The server will start and wait for MCP messages on stdin. You can verify it's running if you see the startup logs.
Test with Claude Desktop
Once connected to Claude Desktop, you can test the tools by asking Claude to use them:
"Use the hello_world tool"
"Echo this message: Hello from WSL!"
"Get server information"
"List all available tools"
Development
Project Structure
Adding New Tools
To add new tools to the MCP server:
Edit
Add a new tool function decorated with
Add proper type hints and docstring
Example:
Reinstall the package (if needed):
pip install -e .Restart Claude Desktop to load the updated tools
Code Quality
The project includes configuration for:
Black: Code formatting
isort: Import sorting
mypy: Type checking
ruff: Linting
pytest: Testing
Run quality checks:
Troubleshooting
Common Issues
Server won't start:
Check that Python 3.10+ is installed in WSL:
python --version
Ensure FastMCP is installed:
pip install fastmcp
Verify virtual environment is activated:
which python
Claude Desktop can't connect:
Verify the paths in
claude_desktop_config.json
are correctCheck that WSL is accessible from Windows
Look at Claude Desktop's logs for connection errors
Test the server manually in WSL first
Tools not appearing:
Restart Claude Desktop after configuration changes
Check server logs for errors
Verify the server is running:
ps aux | grep spec3-mcp-server
WSL-specific issues:
Ensure WSL is properly installed:
wsl --version
Test WSL execution from Windows CMD:
wsl -e python --version
Check WSL distro is running:
wsl -l -v
Logging
The server includes comprehensive logging. Check the console output for:
Server startup messages
Tool execution logs
Error messages and stack traces
To see logs when running via Claude Desktop, you can redirect them to a file by modifying the config:
Getting Help
If you encounter issues:
Check the server logs for error messages
Verify your Python and FastMCP versions
Test the server independently before connecting to Claude Desktop
Check the FastMCP documentation at https://github.com/jlowin/fastmcp
Review Claude Desktop's documentation for MCP configuration
Next Steps
Once you have the local server working:
Add more sophisticated tools for your specific use cases
Implement error handling for robust operation
Add tests to ensure reliability
Explore advanced MCP features like resources and prompts
Consider adding environment variables for configuration
License
MIT License - see LICENSE file for details.
local-only server
The server can only run on the client's local machine because it depends on local resources.
A demonstration MCP server for local development and testing with Claude Desktop on WSL. Provides basic utility tools including greeting messages, echo functionality, and server information retrieval.