Guides
  1. AI

ReadMe's MCP Server

Manage your documentation and project from any AI Agent or CI pipeline.

Connect AI agents like ChatGPT, Claude Code, Cursor, and more. Create, edit, and maintain your documentation with ReadMe’s MCP server.

https://docs.readme.com/mcp

What You Can Do

Once connected, you can ask your agent to:

  • Start a new project. If you don't have a ReadMe account yet, your agent can create your account and project.
  • Create docs. Draft guides, API reference pages, and custom pages using ReadMe's MDX components.
  • Maintain docs. Update pages after a code change, fix outdated content across your site, and reorganize categories and pages.
  • Manage settings. View and update appearance, AI features, SEO, and other project settings.

Get Connected

You can have your agent setup the connection for you, or you can manually setup the MCP server and skills.

Have Your Agent Setup For You (Recommended)

Copy and paste this prompt into your agent to let it handle the connection configuration for you. This will install both the MCP server and the agent skills.

Set me up with the ReadMe skills and MCP server in this agent, then help me create my ReadMe project.

To do this - understand what client + surface you are running in from the options below:

- Cursor IDE, Cursor web, or Cursor CLI
- Claude Code CLI or the desktop Code tab
- Claude Desktop Chat or claude.ai
- ChatGPT web or desktop, Codex desktop app, or Codex CLI
- Any other agent, including local coding agents, or a user who does not want a plugin

Then read the instructions for setup here: https://docs.readme.com/docs/readme-mcp-skills-setup.md and ensure you get the full set of instructions for the client + surface you are in.

## After setup

Once the ReadMe skills are available and you can list tools from the ReadMe MCP server, use the \`setup-project\` skill to set me up with my new ReadMe account and project.

If the skills or MCP tools are not available yet because the client needs a restart or reload, tell the user exactly what to restart and they should resume this conversation after restarting. Don't recommend that they start a new conversation.

Manual Connection

Configuration Options
Connect to this MCP Server

Configure your MCP client to connect to the ReadMe MCP server.

Defaults to ReadMe's MCP server — replace with your own project URL if needed

Authentication and filters— API keys, projects, and branch settings
URL Parameters

Customize which project or version branch to connect to.

Filter to specific projects. Comma-separated list.

Use a specific ReadMe branch. Stable version by default.

Search tools (search, fetch) are not available when using a branch.

Authentication

Authentication to pass to the API for execute functionality. Find yours under Account Settings → API Keys (starts with rdme_).

If your project requires login to view, choose the matching auth type below.

Your Connection URL
https://docs.readme.com/mcp
Add to Cursor

Manual Installation

// .cursor/mcp.json
{
  "mcpServers": {
    "readme": {
      "url": "https://docs.readme.com/mcp"
    }
  }
}
🔑

Do not commit API keys into files. Each key maps to one project, so to work with more than one project, register a separate MCP server for each with its own name and key.

ReadMe Skills

Skills are instructions your agent loads when a task needs them.

To install, either install the official ReadMe plugins on available applications, or run:

npx skills add readmeio/agent-plugins

The skills are as-follows:

SkillWhat it helps your agent do
setup-projectCreate an account and project for new ReadMe users, then add initial content and branding
managing-readme-docsConfirm the right project and branch, and choose between the MCP server and Git
edit-page-contentWrite and update pages in valid MDX using built-in components and reusable content
manage-navigationCreate categories, move and reorder pages, and change titles and slugs
update-project-settingsView and change appearance, AI, SEO, access, and other project settings
mcp-authConnect the MCP server to your project and fix authentication errors

Branches and Bi-Directional Sync

Before editing pages, the skills confirm which branch to work on. Ask your agent to create a new branch off your stable version so you can review its changes before they go live. Project settings and changelog posts aren't versioned, so changes to them apply right away.

If your project uses Bi-Directional Sync, open your agent in the synced repository and it edits your docs as files through Git instead.

To share the setup with your team, install the plugin at project scope (for example, --scope project in Claude Code) and commit the configuration so contributors are prompted to install it.

Available Tools

Once connected, these tools are available through the MCP integration:

  • search — search ReadMe's own documentation by keyword
  • fetch — retrieve a page from ReadMe's documentation by ID
  • update-docs — start the docs update flow for documentation changes
  • list-specs — list the ReadMe's OAS spec files your agent can call
  • search-endpoints — search those OAS spec's paths, operations, and schemas
  • list-endpoints — enumerate all paths and HTTP methods for one of the specs
  • get-endpoint — inspect one endpoint in detail (parameters, security, servers)
  • execute-request — call the ReadMe API with your API key to read and change your project
  • draft-changelog — generate a changelog draft from merged PRs or git history

search and fetch answer questions about how ReadMe works. To read or change your own project's pages, branches, and settings, your agent uses execute-request with your API key.

Use Cases

For Developers: Sync Docs with Code Changes

Keep your documentation in step with every code change. Instead of manually tracking what changed and which doc to update, let your AI figure it out.

What you need:

  • An AI coding assistant (Cursor, Claude Code, VS Code Copilot) connected to ReadMe's MCP server
  • A ReadMe API key configured as the authorization header

The prompt:

Update the ReadMe docs to reflect my recent code changes.

1. Use git tools to see what changed: `git diff HEAD~1` or `git log --oneline -10`
2. For each changed file, use the ReadMe MCP `search` tool to find docs that
   cover that functionality
3. For each relevant doc, use the ReadMe MCP `fetch` tool to get the current
   content
4. Use the ReadMe MCP `update-docs` tool to update any pages that are now
   out of date, or create new pages where documentation is missing

What the AI does:

  1. Runs git diff — sees that src/auth/oauth.ts was updated with a new pkce parameter
  2. Calls search("OAuth authentication") — finds your "Authentication" guide
  3. Calls fetch(id) — reads the current content
  4. Identifies the outdated section and rewrites it with the new PKCE details
  5. Calls update-docs — pushes the updated content back to ReadMe

No tab-switching, no copy-pasting. Your docs stay current as part of your normal development flow.

For Everyone: Update Docs from Your Editor

Not every doc update starts with a code change. Sometimes you just need to tweak a description, add a note, or update a detail across your docs. With the ReadMe MCP server connected, you can do this with a simple natural language request — no need to open the ReadMe dashboard.

Just ask your AI assistant something like:

  • "Update our docs to say the Agent uses Opus 4.6"
  • "Add a note about the new rate limit to our API reference"
  • "Rewrite the authentication section to mention SSO support"

What happens behind the scenes:

  1. Finds your live version by looking up your project's current stable branch.
  2. Creates a new branch (e.g., 3.0_agent-opus-4-6-update) so your live docs are never modified directly.
  3. Fetches the target page from the branch.
  4. Applies your requested changes to the page content.
  5. Verifies the update persisted with a follow-up read to confirm the changes were saved.
  6. Returns a review link so you can preview the changes and merge when ready.

You get a branch-based workflow with a review step — just like a pull request for your docs — without having to manage any of it yourself.

📘

Bi-directional sync note

If your project is synced with a Git repository, the MCP server will verify that writes persist after updating. In rare cases where the Git source of truth overrides API writes, you'll be notified to push the change via Git instead.

For Content Writers: Build and Apply a Style Guide

Use your best-performing content as the template for everything else.

Step 1 — Extract your style from top-performing pages

Use the ReadMe MCP tools to analyze my best-performing documentation.

1. Use `search` to find my top 10 most-viewed or highest-rated pages
2. Use `fetch` to pull the full content of each one
3. Analyze what they have in common: structure, tone, heading patterns,
   code example placement, length, use of callouts, etc.
4. Write a concise style guide based on these patterns

The AI reads your actual best content and distills your team's voice into a reusable style guide — no guesswork, no generic writing advice.

Step 2 — Apply the style guide to underperforming content

Now use the style guide you just created to improve my worst-performing page.

1. Use `search` to find my lowest-rated or least-viewed page
2. Use `fetch` to get its current content
3. Rewrite it following the style guide: match the structure, tone, and
   formatting patterns from the top-performing pages
4. Use `update-docs` to publish the improved version

The result: a data-driven content improvement loop, driven entirely by what already works in your docs.

For CI/CD: Auto-generate Changelogs on Release

Every time you ship a new version, automatically create a changelog entry in ReadMe.

Add this workflow to your repository at .github/workflows/changelog.yml:

name: Generate Changelog on Release

on:
  release:
    types: [published]

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Update ReadMe Changelog
        uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Use ReadMe MCP tools to create a new changelog entry.

            Release version: ${{ github.event.release.tag_name }}
            Release notes:
            ${{ github.event.release.body }}

            Steps:
            1. Use the `search` tool to find the existing Changelog page
            2. Use the `fetch` tool to get its current content
            3. Add a new section at the top for version ${{ github.event.release.tag_name }}
               - Use today's date as the release date
               - Summarize the release notes in a clear, developer-friendly format
               - Group changes into: New Features, Bug Fixes, Breaking Changes
            4. Use `update-docs` to publish the updated changelog

          mcp_config: |
            {
              "mcpServers": {
                "ReadMe MCP": {
                  "url": "https://docs.readme.com/mcp",
                  "headers": {
                    "authorization": "Bearer ${{ secrets.README_API_KEY }}"
                  }
                }
              }
            }
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          README_API_KEY: ${{ secrets.README_API_KEY }}

What you need in GitHub Secrets:

  • ANTHROPIC_API_KEY — your Anthropic API key
  • README_API_KEY — your ReadMe API key (format: rdme_xxx...)

What happens on every release:

  1. The workflow triggers when you publish a release in GitHub
  2. Claude connects to ReadMe's MCP server with your API key
  3. It finds your changelog page, reads the current content
  4. Writes a new, cleanly-formatted entry at the top
  5. Publishes it back to ReadMe - before you've even tweeted about the release

Updated 8 hours ago

Did this page help you?