Mastodon MCP

Instructions

Implementation Reference

• src/mastodon_tool.ts:250-307 (handler)

  Handler function that executes the mastodon_search tool: formats search parameters, calls MastodonClient.search, processes results into sections for accounts, hashtags, statuses, and returns formatted text content.
  async (params: SearchParams) => { const searchParams = { q: params.query, type: params.type, limit: params.limit, resolve: params.resolve, following: params.following, }; const results = await client.search(searchParams); const sections = []; if (results.accounts.length > 0) { const accountsList = results.accounts.map((account, index) => { return `${index + 1}. @${account.acct} (${account.display_name})\n Followers: ${account.followers_count} | Following: ${account.following_count} | Posts: ${account.statuses_count}\n ${account.note.replace(/<[^>]*>/g, '').substring(0, 100)}...\n URL: ${account.url}`; }).join('\n\n'); sections.push(`**Accounts (${results.accounts.length})**\n${accountsList}`); } if (results.hashtags.length > 0) { const hashtagsList = results.hashtags.map((tag, index) => { const todayHistory = tag.history[0]; const uses = todayHistory ? `${todayHistory.uses} uses` : "No recent data"; return `${index + 1}. #${tag.name} (${uses})\n URL: ${tag.url}`; }).join('\n\n'); sections.push(`**Hashtags (${results.hashtags.length})**\n${hashtagsList}`); } if (results.statuses.length > 0) { const statusesList = results.statuses.map((post, index) => { const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : ""; return `${index + 1}. @${post.account.acct}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n Posted: ${new Date(post.created_at).toLocaleString()}\n URL: ${post.url}`; }).join('\n\n'); sections.push(`**Posts (${results.statuses.length})**\n${statusesList}`); } if (sections.length === 0) { return { content: [ { type: "text", text: `No results found for query: "${params.query}"` } ], }; } const summary = `Search results for "${params.query}"`; return { content: [ { type: "text", text: `${summary}\n\n${sections.join('\n\n')}`, }, ], }; }
• src/mastodon_tool.ts:68-91 (schema)

  Zod input schema (SearchSchema) defining parameters for the mastodon_search tool: query, type, limit, resolve, following.
  const SearchSchema = z.object({ query: z.string().describe("Search query text"), type: z .enum(["accounts", "hashtags", "statuses"]) .describe("Type of content to search for") .optional(), limit: z .number() .min(1) .max(40) .describe("Number of results to return (1-40)") .default(20) .optional(), resolve: z .boolean() .describe("Whether to resolve non-local accounts/statuses") .default(false) .optional(), following: z .boolean() .describe("Only search accounts the user is following") .default(false) .optional(), });
• src/mastodon_tool.ts:246-308 (registration)

  Registration of the mastodon_search tool on the MCP server using server.tool, providing name, description, input schema, and handler function.
  server.tool( "mastodon_search", "Search for accounts, hashtags, or posts on Mastodon", SearchSchema.shape, async (params: SearchParams) => { const searchParams = { q: params.query, type: params.type, limit: params.limit, resolve: params.resolve, following: params.following, }; const results = await client.search(searchParams); const sections = []; if (results.accounts.length > 0) { const accountsList = results.accounts.map((account, index) => { return `${index + 1}. @${account.acct} (${account.display_name})\n Followers: ${account.followers_count} | Following: ${account.following_count} | Posts: ${account.statuses_count}\n ${account.note.replace(/<[^>]*>/g, '').substring(0, 100)}...\n URL: ${account.url}`; }).join('\n\n'); sections.push(`**Accounts (${results.accounts.length})**\n${accountsList}`); } if (results.hashtags.length > 0) { const hashtagsList = results.hashtags.map((tag, index) => { const todayHistory = tag.history[0]; const uses = todayHistory ? `${todayHistory.uses} uses` : "No recent data"; return `${index + 1}. #${tag.name} (${uses})\n URL: ${tag.url}`; }).join('\n\n'); sections.push(`**Hashtags (${results.hashtags.length})**\n${hashtagsList}`); } if (results.statuses.length > 0) { const statusesList = results.statuses.map((post, index) => { const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : ""; return `${index + 1}. @${post.account.acct}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n Posted: ${new Date(post.created_at).toLocaleString()}\n URL: ${post.url}`; }).join('\n\n'); sections.push(`**Posts (${results.statuses.length})**\n${statusesList}`); } if (sections.length === 0) { return { content: [ { type: "text", text: `No results found for query: "${params.query}"` } ], }; } const summary = `Search results for "${params.query}"`; return { content: [ { type: "text", text: `${summary}\n\n${sections.join('\n\n')}`, }, ], }; } );
• src/api.ts:152-155 (helper)

  MastodonClient.search helper method called by the tool handler to perform the actual API search request.
  async search(params: SearchParams): Promise<MastodonSearchResults> { const queryParams = this.buildQueryParams(params); return this.request<MastodonSearchResults>(`/api/v2/search${queryParams}`); }
• src/mastodon_types.ts:187-191 (schema)

  TypeScript interface defining the structure of search results returned by Mastodon API (used by client.search).
  export interface MastodonSearchResults { accounts: MastodonAccount[]; statuses: MastodonStatus[]; hashtags: MastodonTrendingTag[]; }
• src/mcp-server.ts:13-14 (registration)

  Top-level call to addMastodonTool which registers all Mastodon tools including mastodon_search.
  // Add Mastodon tool to server await addMastodonTool(server);