# MCP server

The API also serves a Model Context Protocol (MCP) server, so an LLM client such as Claude can look up Toastmasters data itself. Its tools are read-only and use the same data and rules as the REST endpoints.

- URL: `https://tm-api.devinpearson.me/mcp`
- Transport: Streamable HTTP (`POST`), stateless. No API key or sign-in is needed.
- Contact details and members' names are left out of every tool.

Add it to Claude Code:

```bash
claude mcp add --transport http toastmasters https://tm-api.devinpearson.me/mcp
```

Or add it to a client that is configured with a JSON file:

```json
{
  "mcpServers": {
    "toastmasters": {
      "type": "http",
      "url": "https://tm-api.devinpearson.me/mcp"
    }
  }
}
```

The server gives clients these instructions:

> Toastmasters club data for the Region → District → Division → Area → Club hierarchy, from Toastmasters' daily reports.
> Find a club with search_clubs, then call get_club for its standing, Distinguished progress and next actions, or get_club_history for past years and recent changes.
> Call get_area for an area's next actions (for its Area Director), Distinguished status, visit and officer-training rounds, and each club's milestone and outlook.
> Call get_division for a division's Distinguished status, area visit summary, officer training and each area's status, and get_district for every division's and area's status.
> get_club, get_area, get_division and get_district each include month_change: the figures (members, paid and Distinguished clubs, DCP goals, educational awards, new members) for the reported fiscal month against the month before, with the difference, so a report can show what changed last month. It is null in July, when the fiscal year starts again.
> To plan a regrouping, call simulate_area with club numbers, or simulate_division with new areas of club numbers.
> Insights are evaluated as of the report date (as_of), not today. Read toastmasters://rules/dcp for the rules behind them and toastmasters://glossary for terms.
> Club numbers are canonical without leading zeros ("00000113" and "113" are the same club).

## Search clubs

MCP tool `search_clubs` on the server at https://tm-api.devinpearson.me/mcp

Find clubs by name (at least 2 characters) in the current fiscal year, optionally within one district.

**Arguments**

- `name` (string, required): Part of the club's name, e.g. "sages"
- `district` (string, optional): District, e.g. "74"; "U" is undistricted, "F" the Founders District
- `limit` (integer, optional): Most results to return (default 20)

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_clubs","arguments":{"name":"sages"}}}'
```

## Get club

MCP tool `get_club` on the server at https://tm-api.devinpearson.me/mcp

A club's status, membership, DCP goals and insights: good standing, its Club Success Plan deadline, Distinguished progress, ranked next actions, its outlook (doing well, improving, steady, declining or definite worry, with the reasons), as of the report date, and month_change: its members, goals, awards, new members and status against the fiscal month before.

**Arguments**

- `club_number` (string, required): Toastmasters club number, e.g. "113" or "00000113"
- `fiscal_year` (string, optional): Fiscal year as "YYYY-YYYY"; defaults to the current one

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_club","arguments":{"club_number":"113"}}}'
```

## Get club history

MCP tool `get_club_history` on the server at https://tm-api.devinpearson.me/mcp

A club's past fiscal years (goals, Distinguished status, membership) and its recent changes by day, with report glitches removed.

**Arguments**

- `club_number` (string, required): Toastmasters club number, e.g. "113" or "00000113"
- `changes` (integer, optional): Most recent change events to include (default 50)

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_club_history","arguments":{"club_number":"113"}}}'
```

## Get area

MCP tool `get_area` on the server at https://tm-api.devinpearson.me/mcp

An area's totals, its clubs in brief, and insights as of the report date: the Area Director's next actions, the area's Distinguished status, the two visit rounds, officer training rounds, and each club's Distinguished milestone, reminders and outlook (doing well, improving, steady, declining or definite worry, with the reasons). month_change compares the area's totals and each club's with the fiscal month before.

**Arguments**

- `district` (string, required): District, e.g. "74"
- `division` (string, required): Division letter, e.g. "A"
- `area` (string, required): Area number within the division, e.g. "02"
- `fiscal_year` (string, optional): Fiscal year as "YYYY-YYYY"; defaults to the current one

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_area","arguments":{"district":"74","division":"A","area":"01"}}}'
```

## Get division

MCP tool `get_division` on the server at https://tm-api.devinpearson.me/mcp

A division's totals, recognition goals and areas in brief, and insights as of the report date: its Distinguished status, the area visit summary, officer training for the division and each area, and each area's Distinguished status. month_change compares the division's totals and each area's with the fiscal month before.

**Arguments**

- `district` (string, required): District, e.g. "74"
- `division` (string, required): Division letter, e.g. "A"
- `fiscal_year` (string, optional): Fiscal year as "YYYY-YYYY"; defaults to the current one

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_division","arguments":{"district":"74","division":"A"}}}'
```

## Get district

MCP tool `get_district` on the server at https://tm-api.devinpearson.me/mcp

A district's divisions in brief, and insights as of the report date: the month's DCP target and the Distinguished status of every division and area. month_change compares the district's totals and each division's with the fiscal month before.

**Arguments**

- `district` (string, required): District, e.g. "74"; "U" is undistricted, "F" the Founders District
- `fiscal_year` (string, optional): Fiscal year as "YYYY-YYYY"; defaults to the latest one

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_district","arguments":{"district":"74"}}}'
```

## Get data freshness

MCP tool `get_data_freshness` on the server at https://tm-api.devinpearson.me/mcp

How current the data is: the latest club performance snapshot and the latest day of club changes, optionally for one district.

**Arguments**

- `district` (string, optional): District, e.g. "74"

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_data_freshness","arguments":{}}}'
```

## Simulate area

MCP tool `simulate_area` on the server at https://tm-api.devinpearson.me/mcp

Evaluate a hypothetical area made of existing clubs, as of their report date: paid, Distinguished and 20+ member clubs, average goals against the month's target, Area Director visits, payments, the area's Distinguished status with the standard goals (4 paid and 2 Distinguished clubs, 4 and 3, 5 and 3), and what each club still needs. Suspended clubs are listed but not counted.

**Arguments**

- `club_numbers` (array of strings, required): The clubs in the new area

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"simulate_area","arguments":{"club_numbers":["113"]}}}'
```

## Simulate division

MCP tool `simulate_division` on the server at https://tm-api.devinpearson.me/mcp

Evaluate a hypothetical division of new areas, each made of existing clubs, as of their report date: the division's totals and on-track clubs, and each area's paid, Distinguished, 20+ member and 5+ goal clubs, officer training and average goals. A club listed in two areas stays in the first.

**Arguments**

- `areas` (array of objects, required): The new areas and their clubs
  - `area` (string, required): The new area's name, e.g. "A1"
  - `club_numbers` (array of strings, required)

**Example call**

```bash
curl -X POST "https://tm-api.devinpearson.me/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"simulate_division","arguments":{"areas":[{"area":"01","club_numbers":["113"]}]}}}'
```

## Resources

- `toastmasters://rules/dcp` (text/markdown): Club rules. Good standing, Distinguished levels, deadlines and membership counting, as the tools apply them.
- `toastmasters://glossary` (text/markdown): Glossary. Toastmasters reporting vocabulary.
