d4nshields/mcp-meetup

MCP Meetup-Claude Integration Server

Overview

This is a production-quality Model Communication Protocol (MCP) server that seamlessly integrates Meetup.com's event discovery APIs with Anthropic's Claude LLM. The server enables intelligent event discovery, natural language querying, and AI-powered recommendations for Meetup events.

Architecture

Core Components

1. MCP Protocol Handler (MeetupClaudeMCPServer)

   • Manages client connections and tool definitions
   • Handles resource management and server lifecycle
   • Provides standardized MCP interface

2. Authentication Manager (AuthenticationManager)

   • OAuth2 flow implementation for Meetup.com
   • Token lifecycle management and refresh
   • Secure credential handling

3. Event Discovery Engine (EventDiscoveryEngine)

   • Natural language query parameter extraction
   • Dual API support (REST and GraphQL)
   • Intelligent event filtering and ranking

4. Prompt Augmentation Service (PromptAugmentationService)

   • Context-aware prompt enhancement
   • Event data formatting for LLM consumption
   • Smart relevance filtering

5. Claude Integration (ClaudeIntegration)

   • Anthropic API client management
   • Response generation and error handling
   • Configurable model parameters

Data Flow

User Query → Parameter Extraction → Event Discovery → Data Augmentation → Claude Processing → Response

Quick Start

Prerequisites

• Python 3.8+
• Meetup.com account
• Anthropic API account

Installation

# Clone or download the project
cd /home/daniel/work/mcp-meetup

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Run the server
python meetup_claude_mcp_server.py

API Setup Instructions

1. Meetup.com OAuth Setup

1. Visit Meetup OAuth Consumers

2. Click "Create New Consumer"

3. Fill in application details:

   • Application Name: Your app name
   • Application Website: Your website or GitHub repo
   • Redirect URI: http://localhost:8080/oauth/callback
   • Application Description: Brief description of your use case

4. Save the generated:

   • Client ID
   • Client Secret

2. Anthropic API Setup

1. Visit Anthropic Console
2. Create account or sign in
3. Navigate to API Keys section
4. Generate new API key
5. Copy the API key securely

3. Environment Configuration

Required environment variables in .env:

MEETUP_CLIENT_ID=your_meetup_client_id_here
MEETUP_CLIENT_SECRET=your_meetup_client_secret_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

Optional configuration:

MEETUP_ACCESS_TOKEN=your_access_token_if_available
MEETUP_REDIRECT_URI=http://localhost:8080/oauth/callback
LOG_LEVEL=INFO
MAX_EVENTS_PER_QUERY=20
DEFAULT_RADIUS=25

MCP Tools

1. search_meetup_events

Search for Meetup events using natural language queries.

Parameters:

• query (string, required): Natural language search query
• max_results (integer, optional): Maximum events to return (default: 20)

Example:

{
  "query": "Python programming events near San Francisco this week",
  "max_results": 10
}

2. augment_prompt_with_events

Enhance a user prompt with relevant event data for context.

Parameters:

• prompt (string, required): User prompt to augment

Example:

{
  "prompt": "What programming events should I attend this weekend?"
}

3. get_event_recommendations

Get AI-powered event recommendations using Claude with event context.

Parameters:

• query (string, required): Natural language query for recommendations
• preferences (string, optional): Additional preferences or constraints

Example:

{
  "query": "I'm interested in machine learning and networking events",
  "preferences": "Prefer free events, willing to travel up to 30 miles"
}

4. get_oauth_url

Get Meetup OAuth authorization URL for authentication setup.

Parameters: None

MCP Resources

1. meetup://config

Current server configuration and status information.

2. meetup://auth/status

Authentication status with Meetup.com including token validity.

Natural Language Query Examples

The server intelligently extracts parameters from natural language:

Time-based queries:

• "events today"
• "what's happening tomorrow"
• "events this week"

Location-based queries:

• "events near me"
• "meetups in San Francisco"
• "remote events only"

Topic-based queries:

• "Python programming meetups"
• "data science events"
• "startup networking"
• "AI and machine learning"

Combined queries:

• "Python events near me today"
• "remote data science meetups this week"
• "free networking events in San Francisco"

Error Handling

The server includes comprehensive error handling for:

• Authentication errors: Missing credentials, expired tokens
• API errors: Rate limiting, network failures, invalid queries
• Data processing errors: Malformed events, empty results

Security Considerations

• Environment variable configuration prevents credential exposure
• OAuth2 flow implementation follows security best practices
• No persistent storage of user queries or personal data
• Configurable logging levels to control information exposure

Development

Project Structure

mcp-meetup/
├── meetup_claude_mcp_server.py    # Main server implementation
├── requirements.txt               # Python dependencies
├── .env.example                  # Environment configuration template
├── README.md                     # This documentation
├── docs/                         # Additional documentation
│   └── adr/                      # Architecture decision records
└── tests/                        # Test files (future)

Testing

Basic testing can be done by running the server and using MCP client tools:

# Start the server
python meetup_claude_mcp_server.py

# In another terminal, test with MCP client
# (MCP client implementation would go here)

Extending the Server

The modular design makes it easy to extend:

1. Additional APIs: Add other event platforms in EventDiscoveryEngine
2. Enhanced filtering: Extend extract_query_parameters method
3. Caching: Add Redis or memory caching in PromptAugmentationService
4. Additional tools: Add new MCP tools in _setup_tools method

Troubleshooting

Common Issues

1. Authentication failures

   • Verify client ID and secret are correct
   • Check redirect URI matches OAuth consumer settings
   • Ensure access token hasn't expired

2. No events found

   • Try broader search terms
   • Check location spelling and format
   • Verify time parameters are reasonable

3. API rate limiting

   • Reduce query frequency
   • Implement request caching
   • Check API quota usage

4. Claude integration errors

   • Verify Anthropic API key is valid
   • Check API quota and billing status
   • Review prompt length and complexity

Debug Mode

Enable debug logging:

export LOG_LEVEL=DEBUG
python meetup_claude_mcp_server.py

Health Checks

Check server status using MCP resources:

# Check configuration
# Use MCP client to read meetup://config

# Check authentication status
# Use MCP client to read meetup://auth/status

Contributing

Development Workflow

1. Fork repository
2. Create feature branch
3. Implement changes with tests
4. Update documentation
5. Submit pull request

Code Standards

• Follow PEP 8 style guidelines
• Use type hints throughout
• Maintain comprehensive docstrings
• Include unit tests for new features

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check troubleshooting section
2. Review configuration and setup
3. Create detailed bug report with logs
4. Include reproduction steps and environment details

Version: 1.0.0
Last Updated: 2025-07-27
Author: Generated for Dan Shields