Skip to main content
Glama
Sign In
Philly Events MCP Server

Philly Events MCP Server

by anewt225
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

🏛️ Philly Events MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to discover and search Philadelphia events from multiple sources. This project demonstrates modern AI infrastructure patterns including tool-based agents, semantic search, and structured data aggregation.

🎯 Project Overview

This MCP server aggregates events from Philadelphia's top event sources:

  • Do215 - Local indie events, arts, music, nightlife

  • Visit Philly - Tourism-focused events, major attractions

  • Eventbrite - Ticketed events, workshops, professional networking

It provides a unified API that AI agents can use to help users discover things to do in Philadelphia.

Related MCP server: better_luma

🚀 Features

Tools Available

Tool

Description

philly_search_events

Search events across all sources with powerful filters

philly_search_source

Search a specific event source

philly_export_to_calendar

Export events to Google Calendar format

philly_list_categories

List all event categories

philly_list_neighborhoods

List Philadelphia neighborhoods

philly_weekly_digest

Generate a curated weekly event digest

Search Capabilities

  • Text search - Match against titles, descriptions, locations

  • Category filters - Music, food/drink, arts, sports, nightlife, comedy, etc.

  • Neighborhood filters - Fishtown, Center City, Rittenhouse, and 20+ more

  • Date range - Find events for specific time periods

  • Price filters - Free events or max price limits

  • Pagination - Handle large result sets efficiently

📦 Installation

# Clone the repository
git clone https://github.com/anewt225/philly-events-mcp-server.git
cd philly-events-mcp-server

# Install dependencies
npm install

# Build the TypeScript
npm run build

🔧 Usage

Running with stdio (Local Development)

npm start

Running with HTTP (Production)

TRANSPORT=http PORT=3000 npm start

Adding it to Claude

First clone, npm install and npm run build (see Installation) so that dist/index.js exists. Then use the absolute path to that file below.

Claude Code (one command):

claude mcp add philly-events -- node /absolute/path/to/philly-events-mcp-server/dist/index.js

Claude Desktop: open Settings → Developer → Edit Config, or edit claude_desktop_config.json directly:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "philly-events": {
      "command": "node",
      "args": ["/absolute/path/to/philly-events-mcp-server/dist/index.js"]
    }
  }
}

On Windows, use forward slashes or escaped backslashes in the path (for example C:/Users/you/projects/philly-events-mcp-server/dist/index.js). Restart Claude Desktop after saving; the philly_* tools then appear in the tools menu.

💡 Example Queries

Once connected, you can ask Claude things like:

  • "What's happening in Fishtown this weekend?"

  • "Find free outdoor events in Philadelphia"

  • "Show me live music events under $30"

  • "Generate a weekly digest of food and drink events"

  • "Find comedy shows in Center City next Friday"

🏗️ Architecture

philly-events-mcp-server/
├── src/
│   ├── index.ts           # MCP server + tool registration
│   ├── types.ts           # TypeScript interfaces
│   ├── constants.ts       # Configuration constants
│   ├── schemas/           # Zod validation schemas
│   │   └── eventSchemas.ts
│   └── services/          # Business logic
│       └── eventScraper.ts
├── package.json
├── tsconfig.json
└── README.md

Key Design Decisions

  1. MCP Protocol - Uses Anthropic's Model Context Protocol for seamless AI integration

  2. TypeScript - Strong typing for reliability and maintainability

  3. Zod Schemas - Runtime validation with clear error messages

  4. Modular Scrapers - Each source is independent and can be updated separately

  5. In-Memory Cache - Efficient event retrieval within a session

🔜 Roadmap

Phase 2: Intelligence Layer

  • Implement RAG with vector database for semantic search

  • Add preference learning based on user selections

  • Build recommendation engine

Phase 3: Product Features

  • Google Calendar API integration

  • Weekly email digest automation

  • User preference profiles

  • Event similarity matching

🧪 Testing

# Build and verify
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

📊 Event Categories

Category

Description

music

Concerts, live music, DJs

food_drink

Food events, happy hours, tastings

arts_culture

Museums, galleries, exhibitions

sports

Sports games, fitness events

nightlife

Clubs, parties, bar events

comedy

Stand-up, improv, sketch

outdoor

Parks, hiking, outdoor activities

family

Kid-friendly events

community

Neighborhood events, meetups

workshop

Classes, learning events

networking

Professional events

film

Movies, screenings

theater

Plays, musicals

markets

Farmers markets, flea markets

festivals

Festivals, celebrations

🏘️ Neighborhoods

Center City, Rittenhouse, Old City, Northern Liberties, Fishtown, University City, Manayunk, East Passyunk, South Philly, Fairmount, Gayborhood, Chinatown, Queen Village, Graduate Hospital, Brewerytown, Kensington, Port Richmond, Germantown, Chestnut Hill, Mount Airy, Hawthorne, Bella Vista

📄 License

MIT License - Feel free to use and modify for your own projects.

🤝 Contributing

Contributions welcome! This project is designed to be extended:

  • Add new event sources

  • Improve scraping accuracy

  • Enhance category classification

  • Add new tool capabilities

👤 Author

Built as a portfolio project demonstrating:

  • Modern MCP server development

  • AI agent infrastructure

  • Product thinking for local discovery

  • TypeScript best practices

Made with ❤️ for Philadelphia

Available Tools

6 tools
philly_export_to_calendarExport Events to Calendar FormatA
Read-onlyIdempotent

Convert Philadelphia events to Google Calendar format for import.

This tool takes event IDs (from search results) and returns them in Google Calendar JSON format, ready for import via the Google Calendar API.

Args:

  • event_ids (array): Array of event IDs to export (max 50)

  • include_description (boolean): Include full description (default: true)

  • include_source_link (boolean): Include link to original event (default: true)

Returns: Array of Google Calendar event objects ready for API import.

Example workflow:

  1. Use philly_search_events to find events

  2. Note the event IDs from results

  3. Call this tool with those IDs to get calendar format

  4. Import to Google Calendar via API

Inputs: event_ids (required), include_description, include_source_link.

philly_list_categoriesList Event CategoriesA
Read-onlyIdempotent

List all available event categories for filtering Philadelphia events.

Use this to discover what categories are available when searching for events.

Inputs: response_format.

philly_list_neighborhoodsList Philadelphia NeighborhoodsA
Read-onlyIdempotent

List all recognized Philadelphia neighborhoods for filtering events.

Use this to discover what neighborhood filters are available.

Inputs: response_format.

philly_search_eventsSearch Philadelphia EventsA
Read-onlyIdempotent

Search for events across all Philadelphia event sources (Do215, Visit Philly, Eventbrite).

This is the primary tool for discovering events happening in Philadelphia. It aggregates results from multiple sources, deduplicates them, and allows filtering by various criteria.

Args:

  • query (string, optional): Text to search in event titles, descriptions, and locations

  • categories (array, optional): Filter by categories like 'music', 'food_drink', 'arts_culture', 'sports', 'nightlife', 'comedy', 'outdoor', 'family', 'community', 'workshop', 'networking', 'film', 'theater', 'markets', 'festivals'

  • neighborhoods (array, optional): Filter by Philly neighborhoods like 'Fishtown', 'Center City', 'Rittenhouse', 'Northern Liberties', 'Old City', etc.

  • start_date (string, optional): Start date in YYYY-MM-DD format

  • end_date (string, optional): End date in YYYY-MM-DD format

  • is_free (boolean, optional): Only return free events

  • max_price (number, optional): Maximum ticket price in USD

  • limit (number): Max results to return (default: 20, max: 100)

  • offset (number): Pagination offset (default: 0)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: Aggregated event listings from all sources with deduplication.

Examples:

  • "Find live music this weekend" → query="live music", categories=["music"]

  • "Free outdoor events in Fishtown" → is_free=true, categories=["outdoor"], neighborhoods=["Fishtown"]

  • "Comedy shows under $30" → categories=["comedy"], max_price=30

Inputs: limit, query, offset, is_free, +6 more.

philly_search_sourceSearch Specific Event SourceA
Read-onlyIdempotent

Search for events from a specific Philadelphia event source.

Use this when you want to search only one source (e.g., just Do215 or just Eventbrite) rather than aggregating from all sources.

Args:

  • source (string): Event source to search - one of 'do215', 'visitphilly', 'eventbrite'

  • query (string, optional): Search text

  • limit (number): Max results (default: 20)

  • response_format ('markdown' | 'json'): Output format

Available sources:

  • do215: Local indie events, arts, music, nightlife

  • visitphilly: Tourism-focused events, major attractions

  • eventbrite: Ticketed events, workshops, professional events

Inputs: source (required), limit, query, response_format.

philly_weekly_digestGenerate Weekly Event DigestA
Read-onlyIdempotent

Generate a curated weekly digest of Philadelphia events.

This tool searches for events happening in the next 7 days and formats them as a digestible newsletter-style summary, organized by category.

Args:

  • categories (array, optional): Focus on specific categories

  • neighborhoods (array, optional): Focus on specific neighborhoods

  • include_free_only (boolean): Only include free events (default: false)

  • max_events (number): Maximum events in digest (default: 20, max: 50)

  • response_format ('markdown' | 'json'): Output format

Perfect for:

  • Weekly event roundup emails

  • Planning your weekend

  • Discovering new things to do

Inputs: categories, max_events, neighborhoods, response_format, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct operation: discovery (list_categories, list_neighborhoods), search (search_events aggregate, search_source single-source), export, and digest. The aggregate vs single-source search distinction is clearly explained. philly_weekly_digest partially overlaps with philly_search_events since it's essentially a preset filtered search with formatting, but the newsletter framing keeps it distinguishable.

    Naming Consistency5/5

    All tools use a consistent philly_ prefix followed by a verb_noun pattern (list_categories, search_events, export_to_calendar, weekly_digest). No mixing of conventions or casing styles.

    Tool Count5/5

    Six tools is well-scoped for a niche city event aggregator, with each tool earning its place: discovery, search, single-source search, export, and digest. No redundant or trivial tools in the set.

    Completeness4/5

    The surface covers discovery, search, filtering, export, and digest workflows well. The one noticeable gap is a get_event-by-ID tool, which would be useful given that export_to_calendar consumes event IDs yielded by search.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • better_luma

      samthedataman
      A
      license
      A
      quality
      C
      maintenance
      Provides read-only tools for discovering, searching, and browsing events from Luma, Posh, and Partiful platforms, including event details and guest lists, with optional authenticated access to a user's Luma events.
      10
      MIT

    • OpenAgenda MCP

      pipeworx-io
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search event calendars by keyword and list upcoming or date-filtered events from a chosen calendar, returning titles, dates, venues, coordinates, and keywords.
      349 npm
      MIT
    • SyncSo

      SyncSoofficial

      SyncSo-Inc
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to search and retrieve live local happenings in New York City — music, theater, comedy, film, art, sports, festivals, markets, food and drink, classes, tours and nightlife — each with dates, times, prices, booking links and images. Two tools, search_directions and get_details, let assistants answer time-sensitive questions about what is happening nearby and return bookable results.
      2
      MIT