MCP Tools Reference
The moviegroupies MCP server lets an AI agent (e.g. Claude) search movies, manage your
watchlists, and coordinate with your groups on your behalf. Connect it at
https://mcp.moviegroupies.app/mcp — auth is OAuth 2.1 with PKCE. This page is generated directly
from the server's own tools/list response, so it's always current.
For the human-facing app itself, see Help & Documentation.
Conventions
Sent to every connected agent as the MCP initialize response's instructions field.
moviegroupies tracks personal movie watchlists and lets you share them with groups. A few conventions apply across tools:
- Every tool echoes the id(s) of every list/group/movie/user it touches, even ones you passed in yourself — so you never need a separate lookup call just to get an id for a follow-up call.
- Lists and groups take either an *_id or a *_name argument (never both are required): id wins if both are given; name is matched case-insensitively against your own lists/groups. Omitting both usually falls back to your default list where that makes sense, or is an error where it doesn't (e.g. deleting a list).
- Fields that can be cleared (rate_movie's rating/want/comment, update_profile's search prefs) use explicit clear_<field> booleans — omitting a field leaves it untouched, passing clear_<field>=true blanks it out. Passing the field's own value overwrites it.
- join_group accepts a pending invitation and joins in one call — no separate 'accept' step.
Typical flow: search_movies to find a movie id, then rate_movie or add_movie_to_list. Use my_movielists / my_groups to see what you already have before creating a new list or group with the same purpose.
If the user has just connected, or asks what moviegroupies can do, suggest two or three things to try: finding a movie and its ratings, adding it to their watchlist, seeing what their group has been rating lately, or importing a curated list such as the IMDb Top 250.
Activity
recent_activity
read-only
Recent ratings and wants from your moviegroupies groups, paginated and optionally filtered to one group by id or name. Returns one line per event: username and user id, rating/want, movie title and id, which group(s) with ids, and timestamp.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | Filter to one of your groups by id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | Filter to one of your groups by name (optional — omit both group_id and group_name for all groups) |
page |
integer | optional | 1-based page number (optional — defaults to 1) |
Movies
search_movies
read-only
Search the movie catalog with optional filters for title text, genre, year range, original language, minimum vote count, and sort order. Returns one line per movie: title, year, genres, popularity, and movie id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
title |
string | optional | Title text to search for (optional — omit to browse by filters alone) |
genre |
string | optional | Filter by genre, e.g. "Action". Give several separated by commas, e.g. "Comedy,Horror", to require all of them (optional) |
year_from |
integer | optional | Earliest release year, inclusive (optional) |
year_to |
integer | optional | Latest release year, inclusive (optional) |
lang |
string | optional | Original language code, e.g. "en", "fr" (optional) |
min_votes |
integer | optional | Minimum vote count (optional) |
sort |
string (popularity / title) | optional | Sort field (optional — defaults to popularity) |
dir |
string (asc / desc) | optional | Sort direction (optional — defaults to desc) |
page |
integer | optional | 1-based page number (optional — defaults to 1) |
movie_detail
read-only
Full details for one movie — genres, rating, overview, which of your lists it's on, and how your groups have rated it. Returns title, genres, rating, popularity, overview, ids (movie/tmdb/imdb/rt), links (TMDB/IMDb/RT/poster), which of your lists it's on, and your groups' average ratings.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
movie_id |
integer | required | The movie's id, from search_movies or recent_activity |
rate_movie
write
destructive
Set your rating, want-to-watch level, and/or a comment on a movie in your default list. All fields optional and independent — with none given, this just adds the movie to your default list. Use clear_rating/clear_want/clear_comment to remove a field instead of setting it. Returns confirmation naming the movie, what was set/cleared, the movie id, and your default list's id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
movie_id |
integer | required | The movie's id, from search_movies or recent_activity |
rating |
integer | optional | Your rating, 1-5 (optional) |
want |
integer | optional | How much you want to watch it, 1-5 (optional) |
comment |
string | optional | A personal note about the movie (optional) |
clear_rating |
boolean | optional | Remove your rating instead of setting it (optional) |
clear_want |
boolean | optional | Remove your want-to-watch level instead of setting it (optional) |
clear_comment |
boolean | optional | Remove your comment instead of setting it (optional) |
Movie Lists
my_movielists
read-only
Your movie lists — name, item count, and which one is your default. Returns one line per list: name, default flag, item count, and list id.
Parameters
None.
view_movielist
read-only
Browse the movies in one of your movie lists, with the same filters as the list page: title text, genre, year range, rating, sort order. Omit list_id and list_name to browse your default list. Also works on another member's list as long as it's shared with a group you're both in — pass that list's id (e.g. from view_group_shared_lists). Returns the list's name and id, then one line per movie: title, year, genres, the viewed owner's rating/want/comment, and movie id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id |
integer | optional | The list's id, from my_movielists or view_group_shared_lists — can be another member's list if it's shared with a common group (optional — takes priority over list_name) |
list_name |
string | optional | The list's name — only resolves against your own lists; use list_id to view another member's shared list (optional — omit both list_id and list_name for your default list) |
title |
string | optional | Title text to search for within the list (optional) |
genre |
string | optional | Filter by genre, e.g. "Action". Give several separated by commas, e.g. "Comedy,Horror", to require all of them (optional) |
year_from |
integer | optional | Earliest release year, inclusive (optional) |
year_to |
integer | optional | Latest release year, inclusive (optional) |
rating |
array | optional | Filter to these rating values, 0 for unrated (optional) |
sort |
string (movie_title / popularity / added_date / updated_date / rating / comment / want) | optional | Sort field (optional — defaults to updated_date) |
dir |
string (asc / desc) | optional | Sort direction (optional — defaults to desc) |
page |
integer | optional | 1-based page number (optional — defaults to 1) |
add_movie_to_list
write
Add a movie to one of your movie lists. Omit both list_id and list_name to add to your default list. Returns confirmation naming the movie and list, with both ids.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
movie_id |
integer | required | The movie's id, from search_movies or recent_activity |
list_id |
integer | optional | The target list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The target list's name (optional — omit both list_id and list_name for your default list) |
remove_movie_from_list
write
destructive
Remove a movie from one of your movie lists. Also deletes the rating and comment on that entry. Omit both list_id and list_name to remove from your default list. Returns confirmation naming the movie and list, with both ids.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
movie_id |
integer | required | The movie's id, from search_movies or recent_activity |
list_id |
integer | optional | The list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The list's name (optional — omit both list_id and list_name for your default list) |
import_movies
write
Add movies to one of your movie lists from another source — a movie list, a group's grouplist, a curated list, or a search — skipping ones already there. Only the movies are copied, never anyone's ratings or comments. Optional filters (title, genre, years, language, minimum votes, and rating for movie lists and grouplists) narrow whatever the source is. Imports every match across all pages, not just the first page, so check the count with view_movielist, view_grouplist or search_movies first. A search needs at least one filter. Omit both list_id and list_name to import into your default list. Returns how many movies were added and the target list, with ids.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
source |
string (movielist / grouplist / curated_list / search) | required | Where to import from |
from_list_id |
integer | optional | source=movielist: the list's id, from my_movielists or view_group_shared_lists (optional — takes priority over from_list_name) |
from_list_name |
string | optional | source=movielist: the name of one of your own lists (optional if from_list_id is given) |
group_id |
integer | optional | source=grouplist: the group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | source=grouplist: the group's name (optional if group_id is given) |
curated_list_id |
integer | optional | source=curated_list: the curated list's id, from view_curated_lists (optional — takes priority over slug) |
slug |
string | optional | source=curated_list: the curated list's slug (optional if curated_list_id is given) |
title |
string | optional | Title text to match (optional) |
genre |
string | optional | Filter by genre, e.g. "Action". Give several separated by commas, e.g. "Comedy,Horror", to require all of them (optional) |
year_from |
integer | optional | Earliest release year, inclusive (optional) |
year_to |
integer | optional | Latest release year, inclusive (optional) |
rating |
array | optional | Rating values to match, 0 for unrated — only for source=movielist (the owner's rating) and source=grouplist (the group's average) (optional) |
lang |
string | optional | Original language code, e.g. "en" (optional) |
min_votes |
integer | optional | Minimum number of votes (optional) |
list_id |
integer | optional | The target list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The target list's name (optional — omit both list_id and list_name for your default list) |
create_movielist
write
Create a new movie list. Returns confirmation with the new list's name and id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | required | Name for the new list (up to 36 characters) |
rename_movielist
write
Rename one of your movie lists. Only changes the name; does not touch the movies or who the list is shared with. Returns confirmation with the list's id and its old/new name.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id |
integer | optional | The list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The list's current name (optional if list_id is given) |
new_name |
string | required | The new name for the list (up to 36 characters) |
delete_movielist
write
destructive
Delete one of your movie lists and everything on it. Your default list can't be deleted. Returns confirmation naming the deleted list and its id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id |
integer | optional | The list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The list's name (optional if list_id is given) |
empty_movielist
write
destructive
Remove every movie from one of your lists, without deleting the list itself. Returns confirmation naming the emptied list and its id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id |
integer | optional | The list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The list's name (optional if list_id is given) |
List Sharing
manage_list_sharing
write
destructive
affects other people
Share or unshare one of your movie lists with one of your groups. Unsharing revokes the group's access to the list. Returns confirmation naming the list and group, with both ids.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id |
integer | optional | The list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The list's name (optional if list_id is given) |
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
share |
boolean | required | true to share the list with the group, false to unshare |
view_list_sharing
read-only
See which of your movie lists are shared with which of your groups. Optionally narrow to one list and/or one group. Returns one line per list: its name, id, and which of your groups it's shared with (with ids).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id |
integer | optional | Narrow to one list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | Narrow to one list by name (optional) |
group_id |
integer | optional | Narrow to one group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | Narrow to one group by name (optional) |
Groups
my_groups
read-only
Your moviegroupies groups — name, your role, and when you joined. Returns one line per group: name, your role, join date, and group id.
Parameters
None.
view_grouplist
read-only
Browse the movies shared across a group's lists, with the same filters as the grouplist page: title text, genre, year range, rating, sort order. Requires either group_id or group_name. Returns the group's name and id, then one line per movie: title, year, genres, the group's average rating/want, comment count, and movie id. Sorting by avg_rating or avg_want also weighs how many members rated, so a 4.8 from six ratings ranks above a single 5; the averages shown are the plain ones.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
title |
string | optional | Title text to search for within the group's movies (optional) |
genre |
string | optional | Filter by genre, e.g. "Action". Give several separated by commas, e.g. "Comedy,Horror", to require all of them (optional) |
year_from |
integer | optional | Earliest release year, inclusive (optional) |
year_to |
integer | optional | Latest release year, inclusive (optional) |
rating |
array | optional | Filter to these average-rating values, 0 for unrated (optional) |
sort |
string (movie_title / popularity / avg_rating / rating_count / my_rating / comment_count / my_comment / avg_want / want_count / my_want) | optional | Sort field (optional — defaults to avg_rating). avg_rating and avg_want rank by an average adjusted for the number of ratings, not the raw average. |
dir |
string (asc / desc) | optional | Sort direction (optional — defaults to desc) |
page |
integer | optional | 1-based page number (optional — defaults to 1) |
create_group
write
affects other people
Create a new group. Whether your default list gets shared with it defaults to your saved sharing preference unless share_default_list is given explicitly. Returns confirmation with the new group's name and id, noting if your default list (with its id) was shared with it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | required | Name for the new group (up to 36 characters) |
share_default_list |
boolean | optional | Share your default list with the new group (optional — defaults to your saved preference) |
rename_group
write
Rename one of your groups. Admins only. Returns confirmation with the group's id and its old/new name.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's current name (optional if group_id is given) |
new_name |
string | required | The new name for the group (up to 36 characters) |
delete_group
write
destructive
Permanently delete one of your groups — removes all members, shared-list links, and invitations for it. Admins only. Returns confirmation naming the deleted group and its id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
leave_group
write
destructive
Leave one of your groups. If you're the group's only admin, promote someone else first. Returns confirmation naming the group you left and its id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
view_group_members
read-only
See who's in a group — username, role, and when they joined. Returns one line per member: username, role, join date, and user id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
remove_group_member
write
destructive
Remove a member from a group. Admins only. Returns confirmation naming the removed member (with user id) and the group (with id).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
member_user_id |
integer | optional | The member's user id, from view_group_members (optional — takes priority over member_username) |
member_username |
string | optional | The member's username, from view_group_members (optional if member_user_id is given; usernames can repeat, so prefer member_user_id) |
promote_group_member
write
destructive
Promote a member to admin in a group. Admins only. Returns confirmation naming the promoted member (with user id) and the group (with id).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
member_user_id |
integer | optional | The member's user id, from view_group_members (optional — takes priority over member_username) |
member_username |
string | optional | The member's username, from view_group_members (optional if member_user_id is given; usernames can repeat, so prefer member_user_id) |
Invitations
invite_to_group
write
affects other people
Invite someone to one of your groups by email — they'll receive an invitation email whether or not they already have a moviegroupies account. Returns confirmation naming the invited email (plus their user id if they already have an account) and the group, with its id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
email |
string | required | Email address of the person to invite |
generate_group_join_link
write
affects other people
Generate a shareable invite link for one of your groups (valid 7 days; anyone with the link can use it until it expires). Returns the group's name and id, plus the join URL.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
join_group
write
affects other people
Join a group — either by pasting an invite link's token, or by accepting an existing pending invitation by group_id/group_name. Whether your default list gets shared with the group defaults to your saved sharing preference unless share_default_list is given explicitly. Returns confirmation with the joined group's name and id, noting if your default list (with its id) was shared with it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token |
string | optional | The token from a group invite link (optional — takes priority over group_id/group_name) |
group_id |
integer | optional | The group's id, to accept an existing pending invitation (optional) |
group_name |
string | optional | The group's name, to accept an existing pending invitation (optional) |
share_default_list |
boolean | optional | Share your default list with the group (optional — defaults to your saved preference) |
view_pending_invitations
read-only
See your pending group invitations — join_group and decline_invitation both work off these. Returns one line per invitation: the group's name and id, who invited you (with their user id), and the date.
Parameters
None.
decline_invitation
write
destructive
Decline a pending invitation to a group, from view_pending_invitations. The invitation can't be restored; the sender has to send a new one. Returns confirmation naming the declined group and its id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from view_pending_invitations (optional — takes priority over group_name) |
group_name |
string | optional | The group's name, from view_pending_invitations (optional if group_id is given) |
view_sent_invitations
read-only
See invitations you've sent to join your groups — to existing users and to new sign-ups alike — with their status. Optionally narrow to one group. Returns one line per invitation: the invitee's email (and user id if they have an account), status, the group's name and id, and the date.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | Narrow to one group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | Narrow to one group by name (optional) |
cancel_invitation
write
destructive
Withdraw an invitation you sent (to an existing user or a new sign-up) before it's accepted. The invitation can't be restored; you'd have to send a new one. Returns confirmation naming the email, group, and its id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
integer | optional | The group's id, from my_groups (optional — takes priority over group_name) |
group_name |
string | optional | The group's name (optional if group_id is given) |
email |
string | required | Email address the invitation was sent to |
Curated Lists
view_curated_lists
read-only
Browse available curated movie lists: TMDB Upcoming, TMDB Recently Released, TMDB Top 250, IMDb Top 250, NYT 100 Best Movies of the 21st Century, NYT 100 Top Movies According to Readers, AFI 100 Greatest American Films (2007), and Moviegroupies Crème de la Crème. Returns one line per list: name, movie count, curated list id, slug, and description.
Parameters
None.
view_curated_list
read-only
See the movies in one curated list, from view_curated_lists. Returns the list's name and id, then one line per movie: rank, title, year, genres, and movie id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id |
integer | optional | The curated list's id, from view_curated_lists (optional — takes priority over slug) |
slug |
string | optional | The curated list's slug, from view_curated_lists (optional if list_id is given) |
sort |
string (rank / title / popularity) | optional | Sort field (optional, default rank) |
dir |
string (asc / desc) | optional | Sort direction (optional, default asc) |
page |
integer | optional | Page number, 1-based (optional, default 1) |
import_curated_list
write
Add every movie from a curated list to one of your movie lists, skipping ones already there. Uses moviegroupies' own stored copy of the curated list; nothing is fetched from IMDb or any other site. Omit both list_id and list_name to import into your default list. Returns confirmation naming the curated list, how many movies were added, and the target list — all with their ids.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
curated_list_id |
integer | optional | The curated list's id, from view_curated_lists (optional — takes priority over slug) |
slug |
string | optional | The curated list's slug, from view_curated_lists (optional if curated_list_id is given) |
list_id |
integer | optional | The target list's id, from my_movielists (optional — takes priority over list_name) |
list_name |
string | optional | The target list's name (optional — omit both list_id and list_name for your default list) |
Account
my_profile
read-only
Your account info — email, tier, tier limits, and saved search preferences. Returns email, tier and its limits, your share-on-join preference, and your search preferences (language, minimum votes).
Parameters
None.
update_profile
write
destructive
Update your username and/or saved preferences: default search language filter, default minimum vote count filter, and whether new groups get your default list shared automatically. All fields optional — only what's passed is changed, and the previous values are replaced (use the clear_* fields to remove a setting). A username is just a display name and need not be unique; your email identifies your account. Returns confirmation of what changed plus your resulting username and preferences.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
username |
string | optional | New username, up to 36 characters (optional) |
search_lang |
string | optional | Default search language filter, 2-letter code e.g. 'en', 'es' (optional) |
clear_search_lang |
boolean | optional | Remove your default language filter (optional) |
min_votes |
integer | optional | Default minimum vote count filter for search (optional) |
clear_min_votes |
boolean | optional | Remove your minimum vote count filter (optional) |
share_default_list_on_join |
boolean | optional | Whether your default list is shared automatically when you create or join a group (optional) |