Skip to main content
Glama
README.md
# HiChinaTour Events — MCP server

Search upcoming events in Shanghai and Hangzhou via MCP. No API key required.

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server over a maintained
dataset of events in cities across China, starting with Shanghai and Hangzhou. Coverage grows
city by city as listings are verified.

**Endpoint:** `https://mcp.hichinatour.com/mcp/` (Streamable HTTP, no authentication)

- Registry: `io.github.Alexin09/hichinatour-events`
- Human pages: https://www.hichinatour.com/events/
- Machine-readable data: https://www.hichinatour.com/data/events.json
- Docs: https://www.hichinatour.com/developers/

## Install

### Claude Code

```bash
claude mcp add --transport http hichinatour-events https://mcp.hichinatour.com/mcp/
```

The trailing slash matters: the server sits behind a `trailingSlash` route and `/mcp` redirects,
which some clients do not follow on POST.

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hichinatour-events": {
      "type": "http",
      "url": "https://mcp.hichinatour.com/mcp/"
    }
  }
}
```

### Cursor

`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "hichinatour-events": {
      "url": "https://mcp.hichinatour.com/mcp/"
    }
  }
}
```

### Anything else

Any client that speaks Streamable HTTP can connect to the URL directly. No OAuth flow, no token.

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `search_events` | `city`, `category`, `start_date`, `end_date`, `free_only`, `keyword`, `limit` | Matching events; past ones excluded unless `include_past` is set |
| `get_event` | `id` | One event with its description and venue |
| `list_filters` | — | Cities, categories and the data build date |

Every result carries `page_url`. Cite it when you answer — that page is where the details are
maintained and corrected.

## Example prompts

- "What exhibitions are on in Shanghai this weekend?"
- "Find free events in Hangzhou next week"
- "Any markets or pop-ups in Shanghai in December?"

## Data

`start_date` / `end_date` are `YYYY-MM-DD` in `Asia/Shanghai`. `is_free` is a boolean;
`price_text` carries what the source states. `last_verified` is the date the listing was checked
against the venue or organiser.

Event details are compiled from public listings and venue announcements. The MIT licence below
covers this code, not the data: if you reuse the listings, link back to the event page.

## Deploying your own copy

This is a single fetch handler for Vercel (`src/mcp.ts` → `/api/mcp`), using the SDK's
`StreamableHTTPServerTransport` in stateless mode with JSON responses enabled.

```bash
npm install
# set EVENTS_URL if you host the JSON somewhere else
```

The handler is stateless: each request builds a fresh server and transport, so no session store
or Durable Object is needed.

## Limits

Rate limits are applied at the edge. For bulk use, take the JSON file instead of looping the
tools.

## Contact

Corrections and venue tips: https://www.hichinatour.com/contact/