Semurai MCP
Semurai is an SEO MCP server for Claude, ChatGPT, Claude Code, Codex, Cursor and VS Code. Connect your assistant and it gets live keyword data, rankings, Search Console reports, article drafts, content plans, social drafts and publishing. One address, OAuth sign-in, no API keys.
Remote MCP server · OAuth 2.1 sign-in · 62 tools
Server address
https://api.semur.ai/mcpDefinition
An MCP server is a service that gives an AI assistant tools and data through the Model Context Protocol, an open standard for connecting assistants to other software. The assistant reads what each tool does, calls it when your request needs it and works with the result, so a chat can act on real data.
The Semurai MCP server is a remote MCP server at https://api.semur.ai/mcp. It lets the assistant you already use work in your Semurai workspaces: research keywords, check rankings, write article drafts, plan content and publish when you confirm it in your assistant. Inside the app, Semurai’s own AI SEO agent does the same work, and the AI assistants guide covers the setup step by step.
The difference
A general assistant writes well. It does not know your search data or your site until you connect it.
Guesses which keywords matter, with no search volume or difficulty.
Pulls volume, difficulty, CPC, intent and a 12-month trend for up to 10 phrases per call.
Cannot tell you where you rank today.
Reads your tracked positions with 30 or 90 days of daily history, and your Search Console queries.
Writes an article you copy into your CMS by hand.
Saves the article as a draft in Semurai’s SEO editor, then publishes it to WordPress, PrestaShop or the Shoper blog when you confirm.
Loses the plan when the chat ends.
Keeps content plans, calendar entries and tasks in your workspace, where you review and edit them.
How it works
The same address works in every assistant that supports remote MCP servers.
Paste https://api.semur.ai/mcp in your assistant’s connector, plugin or MCP settings, or run one command in your terminal.
Your assistant opens a Semurai page. Sign in, pick a default workspace and click Allow.
Ask for keyword research, a ranking report or an article draft. Your assistant picks the Semurai tools it needs.
Pick your assistant
Each page has the exact setup, what that assistant does best with Semurai and prompts to try.
What your assistant can do
Everything below works in plain language. Ask, and your assistant calls the right tools.
“List my Semurai workspaces and make the online shop the default.”
“Which keywords do our two biggest competitors rank for that we don’t?”
“Show Search Console queries with many impressions and a low CTR.”
“Turn our top cold brew keyword into a full article draft with an FAQ section.”
“Draft three LinkedIn posts about our newest article and queue them for next week.”
“Find WordPress posts with missing meta descriptions and draft the fixes for me to review.”
“Rewrite the titles of our ten weakest espresso machine listings and show me the proposals.”
“Tag the new latte art photos and file them under Holiday campaign.”
“Add a task to update the brewing guide before December and hand it to Tenko.”
Example
Your assistant decides which Semurai tools to call, then answers with the data.
Find keyword ideas for our cold brew guide and tell me which ones we could win this month.
Four low-difficulty phrases where you already rank on page two:
| Keyword | Volume | Difficulty | Your position |
|---|---|---|---|
| cold brew ratio | 6,600 | 18 | 12 |
| cold brew concentrate | 4,400 | 24 | 14 |
| how long to steep cold brew | 2,900 | 12 | 17 |
| cold brew vs iced coffee | 9,900 | 29 | 19 |
Shall I write a draft for “cold brew ratio” in Semurai?
Yes, write it.
Done. “Cold brew ratio: the 1:4 and 1:8 guide” is a draft in your Semurai workspace, ready for your review.
Tool reference
Reads: the tool only reads data. Changes: it creates a draft, a job or a proposal in Semurai, or changes a connected site, store or account. Tools that change something live are flagged, so your assistant asks you to confirm first. The last group, AI graphics and Creative Studio, is only on the full server.
list_workspacesLists your Semurai workspaces with their domain, language, market, your role and which one is this connection’s default.Readsget_workspaceOne workspace in detail: brand kit summary, connected integrations, tracked keywords, the latest site audit and usage limit status.Readsset_default_workspaceChanges the connection’s default workspace, used when you do not name one.Changesget_job_statusChecks a long task started by another tool (queued, running, done or failed) and brings back the result with links to the app.Readsresearch_keywordsSearch volume, difficulty, CPC, competition, intent and a 12-month trend for up to 10 phrases.Readsfind_related_keywordsRelated phrases, long-tail variations and questions for one seed keyword, with volume and difficulty.Readsanalyze_competitorAny domain’s organic profile: traffic, ranking keywords, top keywords, its competitors and 12 months of traffic history.Readsget_competitor_keywordsThe keywords a domain ranks for, filtered by difficulty and volume, to spot easy phrases a competitor wins.Readsfind_keyword_gapKeywords 1-5 competitors rank for and your site does not, ranked by opportunity.Readsget_serp_competitorsThe domains in Google’s live results for one keyword, in position order.Readslist_saved_competitorsThe competitors saved in your workspace, with organic traffic and ranking keywords.Readsget_site_overviewYour domain’s visibility: traffic, ranking keywords, new and lost keywords, position spread and top competitors.Readscheck_rankingsCurrent Google positions of a domain for up to 10 keywords, with the ranking URL.Readsbuild_topic_clusterBuilds and saves a topic cluster from live SEO data: a pillar page and supporting articles with target keywords.Changeslist_tracked_keywordsYour tracked keywords with today’s Google position, weekly and monthly change, volume and ranking URL.Readsget_ranking_historyDaily position history over 30 or 90 days, with the trend and the best and worst positions.Readstrack_keywordsAdds up to 50 keywords to your rank tracker and queues a first check.Changessearch_console_reportGoogle Search Console data: overview, top queries, top pages, one query’s trend or opportunities. Needs Search Console connected in Semurai.Readsaudit_pageA live on-page check of one URL: meta tags, headings, canonical, robots, load time and technical warnings.Readsstart_site_auditStarts a full crawl of your site with a 0-100 health score. Semurai creates fix tasks for the weakest pages when it ends.Changesget_site_auditThe results of a site audit: health score, issue types with recommendations, or the weakest pages.Readsget_performance_reportMeasured results of content published through Semurai: clicks, impressions, winners and underperformers.Readssearch_contentSearches your documents, e-mails, social posts and articles by title, including WordPress-synced ones.Readsget_contentReads one article or document in full, with its status, word count and SEO details.Readscreate_article_outlineDrafts an SEO outline from a topic and your brand kit, so you can review it before the article is written.Changeswrite_articleWrites a full SEO article and saves it as a draft in Semurai’s SEO editor, with image placeholders, or AI images on the full server. Nothing is published.Changesupdate_contentProposes a change to an article or document. Nothing changes until someone approves the proposal in Semurai.Changescreate_documentSaves text as a new draft: a brief, a report, ad copy or an e-mail. Nothing is sent.Changescreate_content_planCreates a content plan over a date range: blog outlines and social post drafts, placed on your calendar. On the full server the plan can also get AI images.Changescreate_campaignPlans a 7-day campaign draft with blog, social, e-mail and ad texts. On the full server its social posts can get AI images. Nothing runs until you launch it in Semurai.Changesget_marketing_occasionsUpcoming holidays, shopping days and seasons in your market, with an idea for each.Readssuggest_internal_linksSuggests internal links for an article from your site’s pages: anchor text, target page and the sentence to place it in.Readscreate_social_postsWrites post drafts for Facebook, Instagram, LinkedIn or X in your brand voice and saves them in Semurai: text only on the official server, with AI images as an option on the full server.Changeslist_social_postsYour social posts: drafts, posts queued for publication and published posts with their results.Readsget_content_calendarYour content calendar for a date range: plan items, drafts, queued posts, scheduled articles and empty days.Readsschedule_contentSets the calendar date of an article or post draft, or adds a new calendar entry.Changesupdate_scheduled_contentChanges the title, date or status of a content plan entry on the calendar.Changesschedule_social_postQueues up to 20 post drafts for automatic publication on your connected Facebook, Instagram or LinkedIn account.Changespublish_articlePublishes an article to WordPress or the PrestaShop blog (as a draft by default) or the Shoper blog, now or at a set time.Changesinspect_wordpress_postReads a live WordPress post: title, status, SEO meta title and description, and images with ALT texts.Readsprepare_wordpress_changesPrepares WordPress SEO fixes (meta titles, descriptions, ALT texts or audit fixes) as a change set to review. The site does not change yet.Changesget_wordpress_changesThe status of a change set, with each fix’s current and proposed value.Readsapply_wordpress_changesApplies the fixes you choose on the live site. A value edited in the meantime is reported, not overwritten.Changesdiscard_wordpress_changesDiscards a prepared change set without touching the site.Changeslist_storesThe Shoper, WooCommerce and PrestaShop stores connected to your workspace.Readssearch_productsSearches a store’s products by name, SKU or id, with prices, status and meta fields.Readsget_productOne product in full: descriptions, meta fields and images with ALT texts.Readssearch_categoriesSearches a store’s categories, or reads one with its full descriptions.Readspropose_product_seoCreates SEO proposals for 1-20 products, with proposed and current values side by side.Changespropose_category_seoCreates an SEO proposal for one category.Changespropose_image_altProposes ALT texts for a product’s images in a Shoper or PrestaShop store.Changeslist_store_proposalsStore changes waiting for approval, made by your assistant, the Semurai chat or its agents.Readsapply_store_proposalsApproves proposals and sends them to the live store. An item changed since the proposal is reported, not overwritten.Changesimport_store_productsRefreshes the products Semurai keeps for a connected Shoper store.Changessearch_mediaSearches your media library by ALT text, title, tags or folder.Readsadd_media_from_urlAdds a file from an https link to your media library, with title, ALT text, tags and folder.Changesupdate_media_detailsSets the title, ALT text and tags of up to 50 files. ALT text a person wrote is kept.Changesorganize_mediaMoves up to 100 files into a folder. Nothing is deleted or renamed.Changeslist_tasksThe tasks on your workspace board, with status, due date and assigned agent.Readscreate_tasksAdds 1-20 tasks to the board, each with an optional description, due date and agent.Changesupdate_taskChanges a task or marks it completed.Changesassign_task_to_agentHands a task to one of Semurai’s AI agents, so you can continue it with that agent in Semurai.ChangesThese tools are only on the full server, at https://api.semur.ai/mcp/full. How to add it
generate_imageCreates 1-4 AI images from a prompt in your brand colours and style and saves them to your media library, in a folder if you name one.Changescreate_canvas_designDesigns an editable social graphic, banner or ad in Canvas from a brief: layout, texts and an AI visual in your brand style, in a few variants.Changescreate_creative_designCreates an editable design in Creative Studio from a brief: a social graphic, carousel, ad, presentation, landing page, UI mockup, e-mail or document. You pick the mode (Template, the fastest; Unique, an original layout; Designer, the most refined), the Brand Kit on or off and whether the Studio may ask questions first. If the run stops with a question, your assistant answers it in the chat.Changesdescribe_mediaAn AI vision model writes alt text, a title and tags for up to 20 media library images in the workspace language. Returns the texts and can save them; alt text a person wrote is kept.Changesrevise_creative_designChanges an existing Creative Studio design from a brief. The result is saved as the design’s next version.Changesanswer_creative_questionAnswers the question a design run is waiting on, for example by choosing one of the designer’s proposed directions, and the design continues.Changeslist_creative_designsLists the workspace’s Creative Studio designs, newest first, with previews and links to the Studio.Readsget_creative_designOne design in detail: its preview, the latest run’s status or the question it waits on, recent versions and variants. It can return the preview image, so your assistant sees the design.Readscancel_creative_runStops a design run in progress. Saved versions stay.Changesset_creative_versionMakes an earlier version, or one of the variants, the current design. The history is kept.Changessave_creative_design_to_librarySaves a Canvas design from Creative Studio (a social graphic, carousel or ad) to the media library: every page or the pages you choose, as PNG or JPG images or as one PDF, in a named folder if you want. Images can have 2× or 3× resolution, and a PNG can have a transparent background.Changessuggest_creative_ideasThree design ideas for a format, each with a title, an angle and a ready prompt, drawn from your Brand Kit, products, occasions and campaigns.Changesset_social_post_mediaSets images from the media library on a social post draft, for example a design you have just saved. The post text stays.ChangesFull server
Semurai has two server addresses. Both use the same sign-in, the same 62 tools and the same 6 prompts. The full one adds 13 tools that make images and designs and work on your Creative Studio designs.
https://api.semur.ai/mcp: the one made for the Claude and ChatGPT app directories, with the 62 tools and 6 prompts above.https://api.semur.ai/mcp/fullgenerate_image: 1-4 AI images from a prompt, in your brand colours and style, saved to the media library, in a folder if you name one.create_canvas_design: an editable social graphic, banner or ad in Canvas, with layout, texts and an AI visual in your brand style, in a few variants.create_creative_design: an editable design in Creative Studio, from a social graphic or carousel to a presentation, landing page, UI mockup, e-mail or document. You pick the mode (Template, Unique or Designer), the Brand Kit on or off and whether the Studio may ask questions first. When it stops with a question, your assistant answers it in the chat.describe_media: alt text, a title and tags for up to 20 library images, written by an AI vision model in the workspace language. It returns the texts and can save them, and alt text a person wrote is kept.answer_creative_question, revise_creative_design, set_creative_version and cancel_creative_run: answer the designer, for example by picking one of the proposed directions, change a design from a brief as its next version, go back to an earlier version or a variant, or stop a run. Saved versions and history stay.list_creative_designs and get_creative_design: your Creative Studio designs with previews, the latest run’s status or open question, versions and variants. Your assistant can see the preview image.save_creative_design_to_library and set_social_post_media: a social graphic, carousel or ad saved to the media library as PNG or JPG images (also in 2× or 3× resolution) or as one PDF, and the images put on a social post draft.suggest_creative_ideas: 3 design ideas for a format, each with a title, an angle and a ready prompt, from your Brand Kit, products, occasions and campaigns.write_article, create_social_posts, create_content_plan and create_campaign. On the official server these stay text only, and articles get image placeholders.semurai-full and sign you in. In Claude Code, /mcp works for the sign-in too.mcpServers: "semurai-full": { "url": "https://api.semur.ai/mcp/full" }.semurai-full.claude mcp add --transport http --scope user semurai-full https://api.semur.ai/mcp/full
claude mcp login semurai-fullcodex mcp add semurai-full --url https://api.semur.ai/mcp/full
codex mcp login semurai-fullThe AI assistants guide walks through both servers step by step.
Prompts
Prompts are saved workflows your assistant runs with a few details from you. In Claude Code they appear as slash commands, for example /semurai:seo_article.
seo_articleResearches a topic, checks the current search results, drafts an outline for you to approve, then writes the article draft in Semurai with internal links.
Argumentstopicfocus_keyword (optional)language (optional)
competitor_gap_reportCompares your site with one competitor: its visibility and keywords, the keyword gap, quick wins and content ideas.
Argumentscompetitor_domain
weekly_seo_reportA weekly report: ranking changes, Search Console traffic, site health, content results, open tasks and next steps.
No arguments
monthly_content_planPlans a month of content from the month’s occasions, your existing content, keyword opportunities and competitor gaps, then puts it on the calendar.
Argumentsmonth (optional)focus (optional)
store_product_seoFinds products with weak titles, descriptions and meta tags, prepares proposals for you to review and applies the approved ones to the store.
Argumentsstore (optional)category (optional)
social_weekPlans a week of social posts from occasions, content worth promoting and free calendar slots, then writes text posts per channel to review and schedule.
Argumentstopic (optional)channels (optional)
Safe by design
Your assistant gets access to your Semurai account through OAuth 2.1, never your password.
OAuth 2.1 with PKCE and automatic client registration. There are no keys or tokens to copy or store.
On the first connection, Semurai shows which app wants to connect and where it returns. Unknown apps get a warning. You pick a default workspace and click Allow.
The assistant works with your role in each workspace (owner, admin or editor), in your default workspace or another one you name.
Articles go to WordPress and PrestaShop as drafts by default. WordPress fixes and store changes stay proposals until you approve them, and content edits become proposals in the app. Tools that publish, such as a Shoper blog post or a queued social post, are flagged, so your assistant asks you to confirm.
What your assistant does counts toward the workspace’s usage limits, the same as work in the app.
Access tokens last one hour and renew on their own. Disconnect an assistant in Settings → AI assistants (MCP), and its access ends at once.
Install reference
Where to add Semurai and what to paste or run. The assistant pages have the full steps.
| Assistant | Where | Paste or run | Sign-in |
|---|---|---|---|
| Claude | Customize → Connectors → Add custom connector | https://api.semur.ai/mcp | Connect, then Allow in Semurai |
| ChatGPT | Web: Plugins → + → Add custom MCP server, authentication OAuth | https://api.semur.ai/mcp | Create as a plugin, then Allow in Semurai |
| Claude Code | Terminal | claude mcp add --transport http --scope user semurai https://api.semur.ai/mcp | /mcp, pick semurai, then Allow |
| Codex | Terminal (shared with the IDE extension and the app) | codex mcp add semurai --url https://api.semur.ai/mcp | codex mcp login semurai, then Allow |
| Cursor | Inside mcpServers in ~/.cursor/mcp.json or .cursor/mcp.json | "semurai": { "url": "https://api.semur.ai/mcp" } | When Cursor asks, sign in and Allow |
| VS Code (GitHub Copilot) | Command Palette → MCP: Add Server → HTTP, ID semurai | https://api.semur.ai/mcp | When the server starts, sign in and Allow |
| Gemini CLI | Terminal | gemini mcp add --transport http semurai https://api.semur.ai/mcp | /mcp auth semurai, then Allow |
| Any other MCP client | Its remote MCP server settings | https://api.semur.ai/mcp | OAuth sign-in, then Allow |
The AI assistants guide covers the first connection, workspaces and disconnecting an assistant. For AI graphics, add the full server as a second connection.
Read more
The setup guide, and what Semurai’s own agents do inside the app.
Every assistant step by step, the first connection, workspaces and how to disconnect.
Read the setup guideSemurai’s own agents plan, write, audit and track rankings inside the app, and you approve the work.
Meet the AI SEO agentInside the app, one brief becomes articles, social posts and store descriptions.
See the content platformFAQ
An MCP server gives an AI assistant tools and data through the Model Context Protocol, an open standard for connecting assistants to software. The assistant reads what each tool does and calls it when your request needs it. A remote MCP server, like Semurai’s, runs online, so you add an address instead of installing anything.
It is Semurai’s remote MCP server at https://api.semur.ai/mcp. It gives your AI assistant 62 tools and 6 ready-made prompts for SEO research, rank tracking, Search Console, audits, content, social posts, publishing, store SEO, media and tasks, all in your Semurai workspaces. A second address, https://api.semur.ai/mcp/full, is the full server: the same tools plus 13 for AI graphics and Creative Studio.
Claude (on the web, Claude Desktop and Cowork), ChatGPT (Business, Enterprise/Edu and Pro, on the web), Claude Code, Codex, Cursor, VS Code with GitHub Copilot and Gemini CLI. Any assistant or agent that supports remote MCP servers with OAuth sign-in can connect with the same address.
No. The first time your assistant connects, you sign in to Semurai with OAuth 2.1, pick a default workspace and click Allow. There are no API keys or tokens to copy, and access tokens renew on their own.
Yes. Install the Semurai plugin on your WordPress site and connect it to Semurai once, and you have a WordPress MCP workflow without building your own server: your assistant publishes or schedules articles from the chat. Articles go to WordPress as drafts by default, or are scheduled for later. SEO fixes for meta titles, descriptions and ALT texts are prepared as a change set you review, and only the fixes you choose are applied. Your assistant asks you to confirm before it changes your site.
Yes, with the full server at https://api.semur.ai/mcp/full. It makes AI images in your brand style and saves them to the media library, editable social graphics, banners and ads in Canvas, and Creative Studio designs such as carousels, presentations and landing pages. It also writes alt texts, titles and tags for library images, and lets articles and social posts get AI images instead of placeholders or text only. In the chat it answers the designer’s questions, revises designs, goes back to earlier versions and puts finished designs on social posts. Add the address as a separate custom connector or MCP server and approve it on the Semurai page. Graphics count toward the workspace’s usage limits, like graphics made in the app.
Each connection has a default workspace you pick when you allow it. Your assistant can list your workspaces and work in another one when you ask. In every workspace your role applies: owners, admins and editors can use the tools.
In Semurai, open Settings → AI assistants (MCP). You see the server address and every connected app with its last use. Disconnect one, and its access ends at once.
Yes. What your assistant does in Semurai counts toward the workspace’s usage limits, the same as work you do in the app.
Inside Semurai, Semur and the specialist agents (Tenko, Dezaina, Somi, Hime, Spynobi and Rankmaru) plan and do the work for you. Over MCP, your own assistant, such as Claude or ChatGPT, calls Semurai’s tools directly. Both work in the same workspace, and your assistant can hand a task to one of the agents.
62 tools in nine areas: workspaces (4), SEO research (10), rankings, Search Console and audits (8), content (10), social and calendar (6), publishing (6), e-commerce (10), media library (4) and tasks (4). 33 only read data, 29 create or change something. The full server adds a tenth area, AI graphics and Creative Studio, with 13 more tools: generate_image, create_canvas_design, create_creative_design, describe_media, revise_creative_design, answer_creative_question, list_creative_designs, get_creative_design, cancel_creative_run, set_creative_version, save_creative_design_to_library, suggest_creative_ideas and set_social_post_media.
Create your Semurai account, add the server address in your assistant and ask your first question.
