MCP服务器示例集

MCP Servers for Business

A collection of production-ready MCP (Model Context Protocol) server examples built with FastMCP, designed to teach you how to create servers that solve real business problems.

Created by hamishfromatech - YouTube

Contents

• What This Repository Is
• Servers Overview
• Quick Start
• Key Concepts Demonstrated
• Architecture Patterns
• Performance & Reliability
• Environment Variables
• Project Structure
• Testing
• Learning Path
• Why FastMCP?
• Data Management
• Contributing
• License

What This Repository Is

This repository contains 27 fully-functional MCP servers that demonstrate patterns, tools, and resources you can use as reference when building your own MCP servers. Each server is self-contained, well-documented, and showcases different aspects of the MCP protocol.

The key insight: These servers don't need to connect to any external applications or services. They're designed to work standalone, proving that you can build powerful, business-valuable MCP servers without complex integrations.

At a glance

Why This Matters

Many MCP tutorials focus on connecting to external APIs (Slack, GitHub, Google, etc.). But real business value often comes from:

• Data organization - Structuring information for AI to query
• Workflow automation - Creating repeatable processes
• Knowledge management - Building searchable systems
• Tracking & analytics - Monitoring habits, time, expenses, revenue, SLAs

This repository proves that MCP servers can deliver all of this without a single external API key.

Servers Overview

Contact & CRM

Revenue & Customer Operations

Procurement & Legal

Knowledge & Documentation

Productivity & Planning

Personal Tracking

Utilities

Developer Tools

Quick Start

Each server is standalone and can be run independently:

# Install FastMCP (and any server-specific extras)
pip install fastmcp

# Or install a server's exact dependencies
pip install -r mcp-servers/invoice-manager/requirements.txt

# Navigate to any server and run it
cd mcp-servers/contact-book
python server.py

Data Persistence: Each server automatically creates a data/ directory on first use. All your data is stored in JSON files and persists across server restarts. You can find your data at mcp-servers/<server-name>/data/<server-name>.json.

Connecting to a client: see the configuration examples in mcp-servers/README.md for Claude Desktop, Claude Code, and the FastMCP CLI.

Key Concepts Demonstrated

1. Tools

Every server exposes tools that AI assistants can call:

@mcp.tool
def create_contact(name: str, email: str = None) -> dict:
    """Create a new contact."""
    # Implementation

2. Resources

Resources provide read-only data access:

@mcp.resource("contacts://all")
def get_all_contacts() -> str:
    """Resource providing all contacts as formatted list."""
    return formatted_contact_list

3. Persistent Storage

All 23 server.py data servers use the same hardened JSON persistence helper:

# Override the data directory for tests or deployments
DATA_DIR = Path(os.environ.get("MCP_DATA_DIR") or (Path(__file__).parent / "data"))
DATA_FILE = DATA_DIR / "contacts.json"

def _load_data() -> dict:
    if DATA_FILE.exists():
        with open(DATA_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    return {"contacts": {}, "next_id": 1}

def _save_data(data: dict) -> None:
    # Serialize once, skip identical writes, write atomically under a lock.
    payload = json.dumps(data, indent=2, default=str)
    with _write_lock:
        if payload == _last_payload:
            return
        _write_payload(payload)   # temp file + os.replace()

Properties shared by every data server:

• Atomic writes - temp file + os.replace(), so an interrupted write cannot corrupt your data
• Thread-safe - a module-level threading.Lock() serialises concurrent tool calls
• Redundant-write skipping - identical payloads are never rewritten
• Single write per mutation - ID allocation does not trigger a second save
• Opt-in debouncing - MCP_WRITE_DEBOUNCE_MS defers disk I/O; pending writes flush on exit and via flush_data
• Built-in backups - backup_data, list_backups, and restore_backup on every data server

Each server stores its data in a dedicated data/ directory:

• Automatic loading - Data loads on server startup
• Auto-save - Changes persist immediately after each operation
• Portable - JSON files can be backed up, migrated, or inspected easily
• No external dependencies - Uses only Python's built-in json module

4. Type Safety

All tools use proper type hints for better AI understanding:

def create_task(
    title: str,
    priority: str = "medium",  # low, medium, high, urgent
    due_date: Optional[str] = None
) -> dict:

5. Enums for Controlled Values

Status values and categories use Enums:

class TaskStatus(str, Enum):
    TODO = "todo"
    IN_PROGRESS = "in_progress"
    DONE = "done"

6. Pydantic Models

Records are validated with Pydantic models and returned as typed objects, so clients get real JSON schemas instead of loose dicts.

Architecture Patterns

CRUD Pattern

Most servers follow a consistent CRUD pattern:

• create_* - Create new records
• get_* - Retrieve by ID
• list_* - List with filters
• update_* - Modify records
• delete_* - Remove records
• search_* - Full-text search

Analytics Pattern

Many servers include analytics tools:

• get_*_summary - Aggregated statistics
• get_*_history - Historical data
• get_*_stats - Overall metrics

Linking Pattern

Knowledge systems use bi-directional linking:

• Track outgoing links in content
• Calculate backlinks
• Find paths between notes
• Identify hub and orphan notes

Business Logic Patterns

The business servers demonstrate reusable domain techniques:

Performance & Reliability

Recent hardening across every data server:

• Atomic, locked writes - no torn files, no lost updates under concurrent tool calls
• Redundant-write skipping - unchanged state never touches the disk
• Optional debouncing - MCP_WRITE_DEBOUNCE_MS trades a small durability window for fewer writes
• Bulk endpoints - bulk_create_* / bulk_add_* collapse N saves into 1
• Backups - snapshot, list, and restore from inside the MCP client
• Incremental indexing - Business Search re-parses only changed files
• TTL skill scanning - Skills Server stats only changed SKILL.md files
• Secure vault - AES/Fernet with PBKDF2-HMAC-SHA256 (600k iterations) and a random salt

Environment Variables

All servers respect these where applicable:

Examples:

# Keep all data in a shared volume
MCP_DATA_DIR=/srv/mcp-data python server.py

# Batch writes for high-throughput ingestion
MCP_WRITE_DEBOUNCE_MS=250 python server.py

# Point the search hub at multiple data roots
MCP_DATA_ROOTS=/srv/mcp-data:/backup/mcp-data python server.py

Project Structure

mcp-servers/
├── README.md                     # Client configuration + per-server index
│
├── # Business servers
├── invoice-manager/              # server.py, README.md, requirements*.txt, tests/
├── support-desk/                 #   "
├── contract-manager/             #   "
├── vendor-manager/               #   "
├── crm/                          #   "
├── contact-book/                 #   "
├── okr-tracker/                  #   "
├── business-analytics/           # Cross-server KPI aggregation (no own data file)
│
├── # Knowledge & productivity
├── document-wiki/
├── zettelkasten/
├── notes-ideas/
├── project-manager/
├── meeting-notes/
├── task-automator/
├── journal/
├── habit-tracker/
├── time-tracker/
├── expense-tracker/
│
├── # Utilities & dev tools
├── file-organizer/
├── inventory-manager/
├── password-vault/               # AES/Fernet + PBKDF2 encryption
├── business-search/              # Cross-server search hub
├── skills-server/                # No persistence (filesystem + TTL cache)
├── code-reviewer/
├── design-audit/
├── tech-debt-tracker/
│
├── # Special layouts
├── career-manager/               # src/career_manager/ package + pyproject.toml
└── kanban-mcp/                   # kanban_server.py, models.py, storage.py, cli.py, index.html

Per-server layout (the common case):

<server-name>/
├── server.py                 # FastMCP server
├── README.md                 # Tool reference and examples
├── requirements.txt          # Runtime dependencies
├── requirements-dev.txt      # Test dependencies
├── tests/                    # pytest suite
│   └── test_<name>.py
└── data/                     # Auto-created on first write (gitignored)
    ├── <name>.json
    └── backups/              # Created by backup_data

Testing

Six servers ship with pytest suites covering their core logic (money math, payment allocation, aging, SLA windows, progress math, search indexing, renewal deadlines, and procurement scoring):

pip install -r mcp-servers/invoice-manager/requirements-dev.txt

pytest mcp-servers/invoice-manager/tests \
       mcp-servers/support-desk/tests \
       mcp-servers/okr-tracker/tests \
       mcp-servers/business-search/tests \
       mcp-servers/contract-manager/tests \
       mcp-servers/vendor-manager/tests

Expected: 64 passed.

Tests isolate themselves with MCP_DATA_DIR / MCP_DATA_ROOTS, so they never touch your real data.

Learning Path

Beginner: Start with these simple, focused servers:

1. Contact Book - Basic CRUD operations
2. Notes & Ideas - Simple note management
3. Habit Tracker - Daily tracking patterns

Intermediate: These introduce more complex relationships:

1. Project Manager - Hierarchical tasks, team management
2. CRM - Multi-entity relationships (leads, deals, customers)
3. Meeting Notes - Agendas, attendees, action items
4. Kanban - Web UI, CLI tools, board management

Advanced: Sophisticated patterns and algorithms:

1. Zettelkasten - Link graphs, pathfinding, hub detection
2. Document Wiki - Wiki link parsing, backlinks
3. Task Automator - Workflows, triggers, template rendering
4. Skills Server - File system scanning, resource templates, dynamic resource generation
5. Career Manager - Resume generation, job application tracking, interview practice, skill gap analysis
6. Code Reviewer - Review sessions, issue tracking with categories/severity, code standards
7. Design Audit - Design systems, accessibility compliance, WCAG tracking
8. Tech Debt Tracker - Interest tracking, snapshots, quality metrics
9. Invoice Manager - Money math, tax/discount totals, payment allocation, aging buckets, recurring schedules
10. Support Desk - Time-based SLA logic, breach detection, compliance metrics
11. OKR Tracker - Bidirectional progress math, hierarchical rollups, check-in history
12. Business Search - Cross-file indexing, incremental cache refresh, multi-source ranking
13. Contract Manager - Date-window logic, notice deadlines, recurring obligations
14. Vendor Manager - Procurement totals, lead-time forecasting, on-time delivery scoring

Why FastMCP?

All servers use FastMCP because it provides:

• Simple decorators - @mcp.tool and @mcp.resource
• Automatic schema generation - Type hints become JSON schemas
• Built-in server - No boilerplate code needed
• Development mode - Hot reload during development

Data Management

Backup

Every data server exposes backup tools your AI client can call:

You can also copy the folder yourself:

cp -r mcp-servers/contact-book/data/ backup/contact-book/

Migration

Data files are plain JSON - you can:

• Edit them directly with any text editor
• Import/export to other systems
• Version control your data with git

Reset

To reset a server's data, delete its JSON file:

rm mcp-servers/contact-book/data/contacts.json

The server will start fresh on next run.

Contributing

This is an educational repository. Feel free to:

• Use these servers as starting points for your own projects
• Suggest improvements or new server ideas
• Report issues or documentation gaps

License

MIT License - Use these examples freely for learning and building your own MCP servers.

Learn more about MCP and AI development: YouTube - Hamish from a Tech

Feedback & Community

Found this MCP server genuinely useful? I'd love to hear from you.

• Email: hamish@atech.industries
• Join our free Open Source AI Builders Club on Skool: https://www.skool.com/open-source-ai-builders-club/about?ref=da946a67c5c646e991b96ea9ce7ad9e4