Content
# 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
```bash
# 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](https://secure.meetup.com/meetup_api/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](https://console.anthropic.com/)
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`:
```bash
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:
```bash
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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:
```bash
# 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:
```bash
export LOG_LEVEL=DEBUG
python meetup_claude_mcp_server.py
```
### Health Checks
Check server status using MCP resources:
```bash
# 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
