MCP Server Examples Collection

A comprehensive collection of Model Context Protocol (MCP) server examples demonstrating various capabilities and use cases. These examples progress from basic tool functionality to advanced real-world integrations, providing hands-on learning materials for MCP development.

🎯 Overview

This collection contains 5 progressively complex MCP server examples, each showcasing different aspects of MCP development:

1. Simple Calculator - Basic tool functionality
2. Weather Service - External API integration
3. File System Access - Resources and local data
4. Task Manager - CRUD operations with persistence
5. GitHub Analyzer - Advanced real-world integration

🚀 Quick Start

Prerequisites

• Python 3.8+ installed on your system
• Claude Desktop application
• Basic understanding of MCP concepts

Installation

1. Clone this repository:

   git clone <repository-url>
   cd mcp-examples

2. Choose an example to start with (we recommend starting with the calculator):

   cd 01-calculator
   pip install -r requirements.txt

3. Configure Claude Desktop by adding the server to your config file:

   {
     "mcpServers": {
       "calculator": {
         "command": "python",
         "args": ["/path/to/mcp-examples/01-calculator/server.py"],
         "env": {}
       }
     }
   }

4. Restart Claude Desktop and start using the tools!

📚 Examples Overview

1. Simple Calculator MCP Server

Difficulty: Beginner
Concepts: Basic tools, parameter validation, error handling

A foundational example demonstrating core MCP tool functionality through mathematical operations.

Features:

• ➕ Basic arithmetic operations (add, subtract, multiply, divide)
• 🔢 Advanced operations (power, square root)
• 📝 Expression evaluation
• ✅ Input validation and error handling

Perfect for: Learning MCP basics, understanding tool registration, and parameter handling.

📖 Full Documentation

2. Weather MCP Server

Difficulty: Intermediate
Concepts: API integration, async operations, environment variables

Demonstrates external API integration with the OpenWeatherMap service.

Features:

• 🌤️ Current weather by city or coordinates
• 📅 Multi-day weather forecasts
• 🔑 API key management
• 🌐 Network error handling
• ⚡ Async HTTP requests

Perfect for: Learning API integration, authentication, and async patterns.

📖 Full Documentation

3. File System MCP Server

Difficulty: Intermediate
Concepts: MCP resources, local data access, security

Showcases both MCP tools and resources for secure file system operations.

Features:

• 📁 Directory listing and navigation
• 📄 File reading and writing
• 🔒 Security and path validation
• 📊 File metadata and information
• 🔍 File search capabilities
• 🌐 MCP resources for file content

Perfect for: Understanding MCP resources vs tools, security considerations, and local data access.

📖 Full Documentation

4. Task Manager MCP Server

Difficulty: Advanced
Concepts: CRUD operations, data persistence, complex data structures

A complete task management system with persistent JSON storage.

Features:

• ✅ Full CRUD operations (Create, Read, Update, Delete)
• 💾 Persistent JSON storage with backups
• 🔍 Advanced search and filtering
• 📊 Statistics and analytics
• 🏷️ Tags, priorities, and assignments
• ⏱️ Time tracking and due dates

Perfect for: Learning data persistence, complex data structures, and state management.

📖 Full Documentation

5. GitHub Repository Analyzer MCP Server

Difficulty: Expert
Concepts: Complex API integration, caching, data aggregation

The most advanced example, providing comprehensive GitHub repository analysis.

Features:

• 📊 Comprehensive repository analysis
• 🔄 Repository comparison
• 📈 Trending and activity analysis
• 📁 File content retrieval
• 🧠 Repository health scoring
• ⚡ Intelligent caching system
• 🚦 Rate limit management

Perfect for: Mastering complex integrations, caching strategies, and advanced analytics.

📖 Full Documentation

🛠️ Configuration Guide

Claude Desktop Setup

Each example includes specific configuration instructions, but here's the general pattern:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "calculator": {
      "command": "python",
      "args": ["/absolute/path/to/01-calculator/server.py"],
      "env": {}
    },
    "weather": {
      "command": "python", 
      "args": ["/absolute/path/to/02-weather/server.py"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    },
    "filesystem": {
      "command": "python",
      "args": ["/absolute/path/to/03-filesystem/server.py"],
      "env": {}
    },
    "task-manager": {
      "command": "python",
      "args": ["/absolute/path/to/04-task-manager/server.py"],
      "env": {}
    },
    "github-analyzer": {
      "command": "python",
      "args": ["/absolute/path/to/05-github-analyzer/server.py"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Using uv (Recommended)

For better dependency management, you can use uv:

{
  "mcpServers": {
    "calculator": {
      "command": "uv",
      "args": ["--directory", "/path/to/01-calculator", "run", "python", "server.py"],
      "env": {}
    }
  }
}

🔑 API Keys Required

Some examples require external API keys:

Weather Server

• Service: OpenWeatherMap
• Get Key: https://openweathermap.org/api
• Environment Variable: OPENWEATHER_API_KEY
• Free Tier: 1,000 calls/day

GitHub Analyzer

• Service: GitHub API
• Get Token: GitHub Settings > Developer settings > Personal access tokens
• Environment Variable: GITHUB_TOKEN
• Permissions: public_repo (and repo for private repositories)
• Free Tier: 5,000 requests/hour

📖 Learning Path

Recommended Order

1. Start with Calculator - Learn MCP fundamentals
2. Try Weather Service - Understand API integration
3. Explore File System - Learn about MCP resources
4. Build with Task Manager - Master data persistence
5. Analyze with GitHub - Advanced integration patterns

Key Concepts by Example

Concept	Calculator	Weather	FileSystem	TaskManager	GitHub
Basic Tools	✅	✅	✅	✅	✅
API Integration	❌	✅	❌	❌	✅
MCP Resources	❌	❌	✅	❌	❌
Data Persistence	❌	❌	❌	✅	✅
Async Operations	❌	✅	❌	❌	✅
Caching	❌	❌	❌	❌	✅
Error Handling	✅	✅	✅	✅	✅

🎨 Usage Examples

Calculator

User: What's 15 + 27?
Claude: I'll calculate that for you.
[Uses add tool: a=15, b=27]
Result: 15 + 27 = 42

Weather

User: What's the weather like in Tokyo?
Claude: I'll get the current weather for Tokyo.
[Uses get_current_weather tool: city="Tokyo"]
Result: Tokyo: 22°C, Clear sky, Humidity 65%

File System

User: List the files in my project directory
Claude: I'll list the contents of your project directory.
[Uses list_directory tool: path="."]
Result: Found 5 items: src/, tests/, main.py, README.md, requirements.txt

Task Manager

User: Create a task to implement user authentication
Claude: I'll create that task for you.
[Uses create_task tool: title="Implement user authentication"]
Result: Task created with ID abc12345

GitHub Analyzer

User: Analyze the React repository
Claude: I'll perform a comprehensive analysis of the React repository.
[Uses analyze_repository tool: owner="facebook", repo="react"]
Result: React has 228k stars, 1.5k contributors, health score 95/100

🔧 Development

Project Structure

mcp-examples/
├── README.md                    # This file
├── 01-calculator/
│   ├── server.py               # Calculator MCP server
│   ├── requirements.txt        # Dependencies
│   └── README.md              # Calculator documentation
├── 02-weather/
│   ├── server.py               # Weather MCP server
│   ├── requirements.txt        # Dependencies
│   └── README.md              # Weather documentation
├── 03-filesystem/
│   ├── server.py               # File system MCP server
│   ├── requirements.txt        # Dependencies
│   └── README.md              # File system documentation
├── 04-task-manager/
│   ├── server.py               # Task manager MCP server
│   ├── requirements.txt        # Dependencies
│   └── README.md              # Task manager documentation
└── 05-github-analyzer/
    ├── server.py               # GitHub analyzer MCP server
    ├── requirements.txt        # Dependencies
    └── README.md              # GitHub analyzer documentation

Common Dependencies

All examples use:

• mcp>=1.0.0 - Core MCP library
• fastmcp>=0.1.0 - Simplified MCP server framework
• typing-extensions>=4.0.0 - Enhanced type hints

Additional dependencies per example:

• Weather: aiohttp for HTTP requests
• GitHub: aiohttp for HTTP requests

Testing

Each example can be tested individually:

# Test a specific server
cd 01-calculator
python server.py

# The server will start and wait for MCP messages
# Use Claude Desktop or MCP Inspector to test

🐛 Troubleshooting

Common Issues

1. Server won't start

   • Check Python version (3.8+ required)
   • Install dependencies: pip install -r requirements.txt
   • Verify file paths in configuration

2. Claude Desktop doesn't see the server

   • Check configuration file syntax (valid JSON)
   • Use absolute paths in configuration
   • Restart Claude Desktop after changes

3. API-based servers fail

   • Verify API keys are set correctly
   • Check internet connectivity
   • Review API key permissions and quotas

4. Permission errors

   • Ensure Python files are executable
   • Check directory permissions
   • Verify environment variables are set

Getting Help

1. Check individual README files for specific troubleshooting
2. Review error messages carefully - they often contain solutions
3. Test with simple examples first (calculator) before complex ones
4. Verify configuration using the provided examples

🎓 Educational Value

For Beginners

• Start with the Calculator to understand MCP basics
• Learn about tool registration and parameter handling
• Understand error handling patterns

For Intermediate Developers

• Explore API integration with the Weather server
• Learn about MCP resources vs tools with File System
• Understand async programming patterns

For Advanced Developers

• Master data persistence with Task Manager
• Learn complex API integration with GitHub Analyzer
• Understand caching strategies and rate limiting

Key Learning Outcomes

After working through these examples, you'll understand:

• ✅ MCP Architecture: Tools, resources, and server patterns
• ✅ API Integration: Authentication, error handling, rate limiting
• ✅ Data Management: Persistence, caching, and state management
• ✅ Security: Input validation, path traversal protection
• ✅ Performance: Async operations, caching, optimization
• ✅ Error Handling: Graceful degradation and user feedback
• ✅ Best Practices: Code organization, documentation, testing

🤝 Contributing

We welcome contributions to improve these examples!

Ways to Contribute

1. Bug Fixes: Report and fix issues in existing examples
2. Documentation: Improve README files and code comments
3. New Examples: Add new MCP server examples
4. Enhancements: Add features to existing servers
5. Testing: Add test cases and validation

Contribution Guidelines

1. Follow existing patterns in code structure and documentation
2. Include comprehensive README for new examples
3. Add proper error handling and input validation
4. Use type hints and clear variable names
5. Test thoroughly before submitting

Ideas for New Examples

• Database Integration: PostgreSQL/MySQL MCP server
• Email Service: SMTP/IMAP integration
• Cloud Storage: AWS S3/Google Drive integration
• AI/ML Service: OpenAI/Anthropic API integration
• Monitoring: System metrics and log analysis
• Social Media: Twitter/LinkedIn API integration

📄 License

This project is licensed under the MIT License - see individual files for details.

🙏 Acknowledgments

• Anthropic for creating the Model Context Protocol
• FastMCP contributors for the simplified server framework
• OpenWeatherMap for providing weather API services
• GitHub for their comprehensive API
• Community contributors who help improve these examples

---

Happy MCP Development! 🚀

Start with the Calculator example and work your way up to building sophisticated MCP integrations.