Paper MCP server

Using the Paper MCP server to connect AI agents with your design files

Overview

What is an MCP server?

You can think of an MCP (Model Context Protocol) server as an authenticated API that an LLM can use to access data from a specific platform or application. In Paper, that means you can use an AI agent to read and write to your design files.

Why is this useful? Well if you’re using an agent to build your design through something like Cursor or Claude Code, it can now use your design files as context. Because Paper is based on web technology and LLMs are really good at understanding the DOM, the results can be impressive.

Because the Paper MCP supports both reading and writing to your files you can use the MCP server to pull context from other sources into your design files. This unlocks a bunch of workflows that were previously tedious to carry out, like syncing tokens from your design system or using real content for your designs.

Getting started

Download the Paper Desktop app

To get started with the Paper MCP server, you need to have the Paper Desktop app installed. Once installed, opening a file in the app will automatically start the MCP server in the background.

Connect to Cursor

To connect to Cursor, make sure you have Cursor installed and then simply click the button below to connect to the Paper MCP server.

This will open the Cursor Settings page where you can add the Paper MCP server by clicking the “Install” button.

Once connected, you should see the Paper MCP server in the list of available tools in Cursor Settings > Tools & MCP. You might have to reload the Cursor window or toggle the MCP server on and off to get the agent to have access to the MCP server.

Connect to Claude Code

To connect to Claude Code, run the following command in either your terminal or the Claude Code extension depending on how you have it installed:

Once connected, you should see the Paper MCP server in the list of available MCPs when you run the /mcp command.

Connect to Codex

Once you have the Codex app installed, navigate to Settings > MCP Servers and add a custom MCP server.

Select the “Streamable HTTP” tab and enter paper as the name and http://127.0.0.1:29979/mcp as the URL and click “Save”.

Once connected, you should see the Paper MCP server in the list of available MCPs.

Connect to Copilot

Make sure you have access to Copilot in VS Code. Once you have access, you can connect to the Paper MCP server by creating a mcp.json file in the .vscode folder of your project and adding the following:

Once entered, you should have the ability to start the MCP server using the “Start” button just above the word “paper”:

Once the server is started, you’ll see its connected status:

Connect to OpenCode

To connect to OpenCode, you need to add the following to your opencode.json file:

Once entered, you should see the Paper MCP server in the OpenCode app. You might need to restart the app to see the changes.

Alternatively, you can run the opencode mcp list command to see the list of available MCPs in the terminal.

Verifying the connection

After you’ve connected the MCP server, you should see the agent icon appear in the Paper Desktop app.

To verify that the connection works, open a new chat and ask the assistant to “create a red rectangle in Paper”. The agent should ask for permission to use the Paper MCP server and then create the rectangle and you should see the rectangle appear in the document.

Errors and troubleshooting

tl;dr: The most common cause of issues is really long running agent sessions. Whenever you run into an issue, first start by restarting the agent session which will re-establish the connection to the MCP server.

You might also run into issues connecting your tool of choice to the MCP in the first place. Often times this requires restarting the tool acting as the MCP host (Cursor, Claude Code, Codex, Copilot, or OpenCode) so it correctly picks up the new MCP server. This is also the best course of action if the MCP is shown as connected but your agent is saying it doesn’t have access to the MCP in the current session.

Because LLMs are not deterministic, they can occasionally hallucinate the tools that are available to them. If you’re seeing a lot of tool calling errors in your agent chat this is because the agent can get the parameters for the tool call wrong, even though they have access to the schema. Once again, the best fix is to turn everything off and then turn it back on again.

If you need to debug some MCP connection issues, you can ask the agent to help you troubleshoot using the link to this documentation as some added context.

Guides

Syncing tokens from Figma

It can be useful to move things like colors and text styles that you already have set up in Figma into Paper so you can use them in your designs. To do this, you need to make sure you have the Figma MCP server installed and set up in the same IDE or CLI tool that you have the Paper MCP server installed in.

Both the Paper MCP and Figma MCP servers use the currently opened file as context, so you need to make sure you have the correct files set up in both apps. You can always ask the agent to tell you what files it sees open in either app to verify that things are working correctly

For our example, we have a small design system set up in Figma that uses a mix of variables and styles and we want to add that information to Paper.

There are some quirks to working with variables or styles in Figma. You need to make sure you have an element selected in Figma that has a variable or style assigned to it. Once you have that, you can ask the agent to create a design system in Paper that matches the Figma file and just let it do the work.

Your agent will ask for permission when it wants to call tools associated with both MCP servers — the Figma MCP server is read only so it’s usually okay to grant it ‘always allow’ permissions. The Paper MCP can read and write, so make sure you’re comfortable with the agent being able to manipulate this specific design file.

The agent will then create a design system sticker sheet in Paper based on the design system in Figma:

Here are some gotchas to watch out for when working with the Figma MCP server:

• It will typically return SVG fills as images and if the SVG is a component instance it tends not to respect any color overrides applied to the component.
• Agents also ignore things like spacer elements that are used to fill in gaps in layouts so you might notice the spacing looks a bit off.
• There are some design elements in Figma that don’t translate well to Paper, like inset borders not being converted to outlines.
• Code connected components in Figma are not reliably converted to Paper.
• Some very large and deeply nested designs can cause errors with the Figma MCP tool calls. You can try to get around this by asking the agent to break down the design into smaller parts and iterate on each part individually.

Using real content from Notion

Designing with placeholder content sucks, but not as much as manually typing out the real content. With the MCP server you can pull real world content into your designs from multiple sources, like Notion for example.

To get started, you need to make sure you have the Notion MCP server installed and set up in the same IDE or CLI tool that you have the Paper MCP server installed in.

For our example, we have a testimonial section in Paper with some Lorem Ipsum placeholder content and a Notion database with a bunch of real testimonials. We can ask the agent to pull in the testimonials from the Notion database and use them in the testimonial section in Paper.

To make it easier, select the testimonial frame in Paper and then ask the agent to “sync the content from the Notion Testimonials database with this frame”.

The agent will ask for some permissions to grab the content from Notion and then begin updating the testimonial section in Paper with the real content.

We can take this a step further and ask the agent to translate the content so we can test how the design holds up in different languages, like German or Spanish.

This really just scratches the surface of what’s possible when you can use real data sources in your designs.

Building a website from a design

It’s never been easier to turn your designs into real websites with Paper and AI agents. Because Paper is based on web technology it’s really easy for agents to translate your designs into code.

Here we have a design for a landing page hero section and we want to make it into a real website:

First, we’re going to make a new folder somewhere on our computer and then make sure we open our agent tool of choice in that folder.

Before we get started, it’s important to remember that when going from design to code, you’ll get the best results if the structure of your design is already optimized for code. In Paper, this means using flex layouts and containers so that the agent can easily understand the layout of the design.

We’re going to ask our agent to use React and Tailwind, which are two technologies the agent is very familiar with, but you can really choose any technologies you want. In Paper, make sure you have the frame selected that you want the agent to build before entering your prompt.

I'd like you to build a website in this folder using the hero section I have selected in Paper. Use React and Tailwind for the styling.

Straight away, the agent will ask for permission to call some Paper MCP tools to examine the design. Because these are read only tools, it’s usually okay to grant it ‘always allow’ permissions. While it’s examining the frame, you’ll get some visual feedback in Paper.

After the agent has examined the design, it will ask for permission to call some more commands to build the website in the new folder. Because it’s a new folder that we’ve set up just for this project it’s fine to grant it ‘always allow’ permissions, but if you’re working in an existing project you might want to be more selective about which permissions you grant.

This whole process will take a few minutes and depending on your tooling, you might need to babysit the agent to give it permissions.

If you are new to web development, the result might be a bit confusing. When the agent is done, it will likely run some commands like npm run dev which starts up a local development server on your computer. This server has a weird URL, usually something like http://localhost:5173 or http://localhost:3000, which you can open in your browser to see the website.

This website isn’t live — it’s running locally on your computer so that when you make changes to the code, you can see the changes immediately in the browser.

Our agent got pretty close to our original design, largely because the file we gave it was well structured and the hero frame was relatively small. The larger the thing you’re trying to build, the more likely the agent will get stuff wrong so it makes sense to start with a small part of the design and then build up from there.

This seems like a good point to make a checkpoint, so we’ll ask the agent to set up git in this folder and commit the changes we’ve made so far.

Can you add git to this folder and commit the changes we've made so far?

If you’re new to git, it’s a version control system that allows you to track changes to your code and revert to previous versions if needed. Every time we want to make a substantial change to the website, we’ll commit our changes so we can revert to a previous version if needed.

If we want to go back to a previous version, we can ask the agent to simply check out that commit and the website will be exactly as it was at that point in time. Bigger changes can be put onto new branches and merged back into the main branch when ready, so that we can keep our changes isolated from the main codebase.

Our website isn’t really that responsive yet, so we’ll ask the agent to make it responsive based on some other frames we have set up in Paper.

Can you add some responsive breakpoints to the website based on the frames I have selected in Paper? Each frame is a different breakpoint.

After a bit of back and forth adjusting a few things, our website is now responsive and looks great on all devices.

We can ask the agent to commit the changes we’ve made so far and then we can deploy the website to a hosting provider.

And that’s it — building out the rest of the website is a matter of asking the agent to continue building out the other sections based on the designs we have set up in Paper. Happy prompting.

Reference

Tools and capabilities

The paper MCP server exposes the following tools, but for the most part you won’t need to use them directly.

• get_basic_info — File name, page name, node count, and list of artboards with dimensions.
• get_selection — Details about the currently selected nodes (IDs, names, types, size, artboard).
• get_node_info — Details for a node by ID (size, visibility, lock, parent, children, text content).
• get_children — Direct children of a node (IDs, names, types, child counts).
• get_tree_summary — Compact text summary of a node’s subtree hierarchy (optional depth limit).
• get_screenshot — Screenshot of a node by ID (base64 image; optional scale 1x or 2x).
• get_jsx — JSX for a node and its descendants (Tailwind or inline-styles format).
• get_computed_styles — Computed CSS styles for one or more nodes (batch).
• get_fill_image — Image data from a node that has an image fill (base64 JPEG).
• get_font_family_info — Look up whether a font family is available (user’s machine or Google Fonts); inspect weights and styles.
• get_guide — Retrieve guided workflows for topics (e.g. figma-import for Figma import steps).
• find_placement — Suggested x/y on the canvas to place a new artboard without overlap.
• create_artboard — Create a new artboard; optional name and styles (e.g. width, height).
• write_html — Parse HTML and add or replace nodes (insert-children or replace mode).
• set_text_content — Set text content of one or more Text nodes (batch).
• rename_nodes — Rename one or more layers (batch).
• duplicate_nodes — Deep-clone nodes; returns new IDs and a descendant ID map.
• update_styles — Update CSS styles on one or more nodes.
• delete_nodes — Delete one or more nodes and all their descendants.
• start_working_on_nodes — Mark artboards as being worked on (show indicator).
• finish_working_on_nodes — Clear the working indicator from artboards.