# MCP Server Framework
A general-purpose Model Context Protocol (MCP) server that provides tools for Claude Code and Claude Desktop.
## Quick Start
```bash
# Install dependencies
cd mcp-server
pip install -r requirements.txt
# Test the server runs (Ctrl+C to stop)
PYTHONPATH=src python -m mcp_server.server
```
## Project Structure
```
mcp-server/
├── src/mcp_server/
│ ├── server.py # Main FastMCP server
│ ├── config.py # Environment-based configuration
│ └── tools/
│ ├── __init__.py # Tool registry
│ ├── echo_tool.py # Example: basic echo tools
│ ├── datetime_tool.py # Example: date/time utilities
│ └── file_tool.py # Example: file operations
├── configs/ # Client configuration templates
└── requirements.txt
```
## Configuration
The server is configured via environment variables:
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_SERVER_NAME` | Display name for the server | `mcp-server` |
| `MCP_LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` |
| `MCP_ALLOWED_PATHS` | Comma-separated paths for file tools | (none) |
| `MCP_CUSTOM_VAR_*` | Custom variables accessible via config | (none) |
## Included Tools
### Echo Tools
- `echo` - Echo back a message
- `echo_uppercase` - Echo in uppercase
- `echo_reverse` - Echo reversed
### DateTime Tools
- `get_current_time` - Get current UTC time
- `get_timestamp` - Get current Unix timestamp
- `parse_timestamp` - Convert timestamp to readable format
- `time_difference` - Calculate time between two timestamps
### File Tools (requires `MCP_ALLOWED_PATHS`)
- `list_directory` - List directory contents
- `read_file` - Read file contents
- `get_file_info` - Get file/directory metadata
- `get_allowed_paths` - Show configured allowed paths
## Setting Up Clients
### Claude Desktop
1. Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
2. Add your server configuration:
```json
{
"mcpServers": {
"my-mcp-server": {
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "/full/path/to/mcp-server",
"env": {
"PYTHONPATH": "/full/path/to/mcp-server/src",
"MCP_ALLOWED_PATHS": "/Users/you/Documents"
}
}
}
}
```
3. Restart Claude Desktop completely (Cmd+Q, then relaunch)
### Claude Code
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"my-mcp-server": {
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "${workspaceFolder}/mcp-server",
"env": {
"PYTHONPATH": "${workspaceFolder}/mcp-server/src",
"MCP_ALLOWED_PATHS": "${workspaceFolder}"
}
}
}
}
```
## Adding New Tools
1. Create a new file in `src/mcp_server/tools/`:
```python
# src/mcp_server/tools/my_tool.py
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from mcp.server.fastmcp import FastMCP
from ..config import ServerConfig
def register(mcp: "FastMCP", config: "ServerConfig") -> None:
"""Register my tools with the server."""
@mcp.tool()
def my_function(param: str, count: int = 1) -> str:
"""
Description shown to Claude.
Args:
param: What this parameter does
count: Optional count with default
Returns:
What the tool returns
"""
return f"Result: {param} x {count}"
```
2. Register it in `src/mcp_server/tools/__init__.py`:
```python
def register_all_tools(mcp: "FastMCP", config: "ServerConfig") -> None:
from . import echo_tool, datetime_tool, file_tool, my_tool # Add import
echo_tool.register(mcp, config)
datetime_tool.register(mcp, config)
file_tool.register(mcp, config)
my_tool.register(mcp, config) # Add registration
```
3. Restart Claude Desktop/Code to pick up the new tool.
## Tool Design Guidelines
1. **Clear docstrings**: The description and parameter docs are sent to Claude
2. **Type hints**: All parameters and returns need type hints (defines the JSON schema)
3. **Return strings**: Tools should return string results for best compatibility
4. **Error handling**: Return user-friendly error messages rather than raising exceptions
5. **Use config**: Access `config` for environment-specific settings (like allowed paths)
## Troubleshooting
**Server won't start:**
- Ensure `PYTHONPATH` includes the `src` directory
- Check that `mcp` package is installed: `pip install mcp[cli]`
**Tools not appearing in Claude:**
- Verify the config JSON is valid
- Check the `cwd` path is correct
- Restart Claude Desktop completely (Cmd+Q on Mac)
**File tools return "not in allowed directories":**
- Set `MCP_ALLOWED_PATHS` to comma-separated directory paths
- Paths must be absolute
## Dependencies
- Python 3.10+
- `mcp[cli]>=1.0.0`
