mastodon_get_timeline
Fetch posts from Mastodon timelines including home, public, or local feeds to monitor social activity and content.
Instructions
Fetch posts from Mastodon timelines (home, public, or local)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeline_type | No | Type of timeline to fetch | home |
| limit | No | Number of posts to fetch (1-40) | |
| max_id | No | Get posts older than this ID | |
| since_id | No | Get posts newer than this ID |
Implementation Reference
- src/mastodon_tool.ts:168-205 (handler)The handler function that implements the core logic of the 'mastodon_get_timeline' tool: processes parameters, fetches timeline data via MastodonClient methods, formats the response as a text list of posts, and returns it in MCP content format.async (params: TimelineParams) => { const timelineParams = { limit: params.limit, max_id: params.max_id, since_id: params.since_id, }; let posts; switch (params.timeline_type) { case "home": posts = await client.getHomeTimeline(timelineParams); break; case "public": posts = await client.getPublicTimeline(timelineParams); break; case "local": posts = await client.getLocalTimeline(timelineParams); break; default: throw new Error(`Unknown timeline type: ${params.timeline_type}`); } const summary = `Found ${posts.length} posts from ${params.timeline_type} timeline`; const postsList = posts.map((post, index) => { const reblogInfo = post.reblog ? ` (reblogged from @${post.reblog.account.acct})` : ""; const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : ""; return `${index + 1}. @${post.account.acct}${reblogInfo}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n Posted: ${new Date(post.created_at).toLocaleString()}\n URL: ${post.url}`; }).join('\n\n'); return { content: [ { type: "text", text: `${summary}\n\n${postsList}`, }, ], }; }
- src/mastodon_tool.ts:36-56 (schema)Zod schema defining the input parameters for the mastodon_get_timeline tool: timeline_type (home/public/local), limit (1-40), max_id, since_id.const TimelineSchema = z.object({ timeline_type: z .enum(["home", "public", "local"]) .describe("Type of timeline to fetch") .default("home"), limit: z .number() .min(1) .max(40) .describe("Number of posts to fetch (1-40)") .default(20) .optional(), max_id: z .string() .describe("Get posts older than this ID") .optional(), since_id: z .string() .describe("Get posts newer than this ID") .optional(), });
- src/mastodon_tool.ts:164-206 (registration)MCP server tool registration for 'mastodon_get_timeline', including name, description, input schema reference, and inline handler function.server.tool( "mastodon_get_timeline", "Fetch posts from Mastodon timelines (home, public, or local)", TimelineSchema.shape, async (params: TimelineParams) => { const timelineParams = { limit: params.limit, max_id: params.max_id, since_id: params.since_id, }; let posts; switch (params.timeline_type) { case "home": posts = await client.getHomeTimeline(timelineParams); break; case "public": posts = await client.getPublicTimeline(timelineParams); break; case "local": posts = await client.getLocalTimeline(timelineParams); break; default: throw new Error(`Unknown timeline type: ${params.timeline_type}`); } const summary = `Found ${posts.length} posts from ${params.timeline_type} timeline`; const postsList = posts.map((post, index) => { const reblogInfo = post.reblog ? ` (reblogged from @${post.reblog.account.acct})` : ""; const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : ""; return `${index + 1}. @${post.account.acct}${reblogInfo}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n Posted: ${new Date(post.created_at).toLocaleString()}\n URL: ${post.url}`; }).join('\n\n'); return { content: [ { type: "text", text: `${summary}\n\n${postsList}`, }, ], }; } );
- src/api.ts:128-143 (helper)Supporting helper methods in MastodonClient class: getHomeTimeline, getPublicTimeline, and getLocalTimeline, which perform the actual API requests to fetch timeline data used by the tool handler.// Timeline methods async getHomeTimeline(params: TimelineParams = {}): Promise<MastodonStatus[]> { const queryParams = this.buildQueryParams(params); return this.request<MastodonStatus[]>(`/api/v1/timelines/home${queryParams}`); } async getPublicTimeline(params: TimelineParams = {}): Promise<MastodonStatus[]> { const queryParams = this.buildQueryParams(params); return this.request<MastodonStatus[]>(`/api/v1/timelines/public${queryParams}`); } async getLocalTimeline(params: TimelineParams = {}): Promise<MastodonStatus[]> { const localParams = { ...params, local: true }; const queryParams = this.buildQueryParams(localParams); return this.request<MastodonStatus[]>(`/api/v1/timelines/public${queryParams}`); }