MCP Tools Reference

The InstaCharts MCP server gives AI apps 17 tools. Your AI assistant picks the right tool based on what you ask, so you don’t need to name tools in your prompts. This page lists each tool, what it does and the inputs it takes, which helps when you want to understand what an assistant can do or are building your own agent.

MCP server URL: https://api.instacharts.io/mcp

How the data is organized

Data lives in sheets, sheets live in workspaces, and each chart is built on one sheet. A typical flow is:

list_workspaces to pick a workspace.
create_sheet, import_from_url or create_upload_link to add the data (or list_sheets and read_sheet to use data already in InstaCharts).
update_chart to set up the sheet’s first chart, or create_chart for another one.
get_chart_image to check how the chart looks.
share_chart for a public link and embed code.

To add a company logo, the assistant puts the image in the workspace’s shared assets with import_asset_from_url or create_asset_upload_link, then places it on a chart with the images input of create_chart or update_chart.

Columns can be named by their header text or by their id. Each new sheet comes with a blank first chart, returned as firstChartId, which the assistant sets up with update_chart.

Tool summary

Tool	What it does	Permission	Task
`list_workspaces`	Lists your workspaces and whether you can edit in each one	View	Free
`list_sheets`	Lists the sheets in a workspace with their size	View	Free
`read_sheet`	Reads a sheet’s columns and a page of its rows	View	Free
`list_charts`	Lists the charts built on a sheet	View	Free
`get_chart_image`	Renders a chart as a PNG image	View	1 task
`create_sheet`	Creates a sheet from CSV text or rows	Edit	1 task
`import_from_url`	Creates a sheet from a data file at a public link	Edit	1 task
`create_upload_link`	Returns a one-time link for uploading a data file	Edit	1 task for the upload
`add_rows`	Adds up to 1,000 rows to a sheet	Edit	1 task
`update_rows`	Changes cells in existing rows	Edit	1 task
`delete_rows`	Deletes rows from a sheet	Edit	1 task
`create_chart`	Creates a chart on a sheet	Edit	1 task
`update_chart`	Changes a chart’s columns, type and settings	Edit	1 task
`share_chart`	Makes a chart public and returns its link and embed code	Edit	1 task
`list_assets`	Lists the images in a workspace’s shared assets	View	Free
`import_asset_from_url`	Adds an image from a public link to the shared assets	Edit	1 task
`create_asset_upload_link`	Returns a one-time link for uploading an image file	Edit	1 task for the upload

Tools that need the edit permission only appear when you approve Create and edit your sheets, charts and embeds while connecting the AI app. See Permissions and Tasks.

Read tools

list_workspaces

Lists the workspaces your account can use, and whether you can edit in each one. This is where the assistant finds a workspaceId. Only workspaces on a paid plan are listed.

list_sheets

Lists the sheets (data tables) in a workspace along with their size.

Input	Required	Description
`workspaceId`	Yes	The workspace to list

read_sheet

Reads a sheet’s columns (id, name and type) and a page of its rows. Each row has a rowId that update_rows and delete_rows use.

Input	Required	Description
`sheetId`	Yes	The sheet to read
`offset`	No	Rows to skip. Default 0
`limit`	No	Rows to return. Default 100, at most 1,000

list_charts

Lists the charts built on a sheet.

Input	Required	Description
`sheetId`	Yes	The sheet whose charts to list

get_chart_image

Renders a chart as a PNG image so the assistant can see how it looks. Counts as one task.

Input	Required	Description
`chartId`	Yes	The chart to render

Sheet tools

create_sheet

Creates a sheet in a workspace from CSV text or an array of rows, with the header row first. Column types (text, number, date, percent, currency) are detected from the values, and the workspace’s plan limits the rows and columns. Returns the new sheet with its columns and firstChartId.

Input	Required	Description
`workspaceId`	Yes	The workspace for the new sheet
`name`	No	Sheet name, up to 100 characters
`csv`	One of `csv` or `rows`	Comma separated text with a header row
`rows`	One of `csv` or `rows`	Rows of cell values, header row first

This tool suits small datasets. For a file at a public link use import_from_url, and for a local file or more than a few hundred rows use create_upload_link.

import_from_url

Creates a sheet from a data file at a public web address. InstaCharts downloads the file itself, so the data never has to pass through the conversation. Good sources include an open data portal’s CSV or JSON export link, a raw file on GitHub (raw.githubusercontent.com) or a Google Sheet published to the web as CSV.

The link has to download the file directly, be public and use https://. A link to a web page that displays the data is refused. CSV, TSV, Excel, OpenDocument, Numbers and JSON files work, up to the plan’s file size. An Excel file with several pages makes one sheet per page.

Input	Required	Description
`workspaceId`	Yes	The workspace for the new sheet
`url`	Yes	The `https://` address of the file
`name`	No	Sheet name. Without one, the sheet takes the file’s name

To keep a sheet in sync with a link from the InstaCharts app, see Import and Sync from a Link.

create_upload_link

Returns a one-time upload link (uploadUrl) that turns a data file into a new sheet. This is meant for files and datasets too large to send as CSV text. The file has to be sent within 15 minutes as an HTTP POST with multipart/form-data, with the file in a field named file:

curl -F "file=@sales.csv" <uploadUrl>

On Windows PowerShell use curl.exe. CSV, TSV, Excel, OpenDocument, Numbers and JSON files work, up to the size in maxFileSizeMB. The upload’s response is the new sheet, the same as create_sheet returns. Each link works once. Creating the link is free, and the upload counts as one task.

This tool needs an AI app that can send a file, such as one that can run commands (ex: Claude Code) or make HTTP requests.

Input	Required	Description
`workspaceId`	Yes	The workspace for the new sheet
`name`	No	Sheet name. Without one, the sheet takes the file’s name

add_rows

Appends up to 1,000 rows to a sheet. Each row is an object of column name (or id) and value. Every chart on the sheet updates with the new rows.

Input	Required	Description
`sheetId`	Yes	The sheet to add to
`rows`	Yes	Ex: `[{"Region": "East", "Sales": 120}]`

update_rows

Changes cells in existing rows, found by the rowId from read_sheet. Only the columns sent are changed.

Input	Required	Description
`sheetId`	Yes	The sheet to change
`changes`	Yes	Up to 1,000 changes. Ex: `[{"rowId": 3, "values": {"Sales": 150}}]`

delete_rows

Deletes rows by the rowId from read_sheet. Deleted rows can’t be recovered.

Input	Required	Description
`sheetId`	Yes	The sheet to change
`rowIds`	Yes	Up to 1,000 row ids

Chart tools

create_chart

Creates a chart on a sheet. The workspace’s saved theme, fonts, colors and locale are applied.

x is the category or date column.
y is the number column being measured. Without y, the chart counts rows for each x value.
groupBy splits the values into series for grouped and stacked chart types. On a heatmap it is the second category.
aggregate defaults to sum for a number column and count for other columns.
filters limits the chart to the rows that match, such as three countries out of a list of hundreds.
limit shows only the top items, such as a top 5 chart.

Input	Required	Description
`sheetId`	Yes	The sheet to chart
`type`	Yes	The chart type (see below)
`x`	Yes	Column name or id for the x axis
`y`	No	Column name or id for the values
`groupBy`	No	Column name or id that splits the data into series
`aggregate`	No	`sum`, `count`, `average`, `median`, `min`, `max`, `distinct`, `valid` or `missing`. See Aggregation
`dateGrouping`	No	`year`, `quarter`, `month`, `week`, `day`, `monthOfYear` or `dayOfWeek`
`title`	No	Chart title
`subtitle`	No	Chart subtitle
`caption`	No	Text under the chart
`xTitle`	No	Title on the x column’s axis. See Axis titles
`yTitle`	No	Title on the y column’s axis. See Axis titles
`showAxisTitles`	No	`true` shows both axis titles and `false` hides them
`name`	No	Chart name in the sheet’s chart list
`theme`	No	A chart theme, such as `midnight` or `studio`. See Colors
`colorScheme`	No	One of the InstaCharts color schemes. See Colors
`color`	No	Hex color for plain bar, line, area and scatter charts, such as `#1f77b4`
`bgColor`	No	Hex background color for the chart
`textColor`	No	Hex color for the chart’s text
`sort`	No	`auto`, `x`, `y` or `none`
`sortDescending`	No	`true` puts the largest value or last label first
`horizontal`	No	Bar charts only. Horizontal bars suit long category names
`width`, `height`	No	Chart size in pixels, 200 to 3,000
`gaugeMin`, `gaugeMax`, `gaugeTarget`	No	Gauge charts only
`images`	No	Logos and other images drawn on the chart. See Images
`filters`	No	The rows the chart uses. See Filters
`limit`	No	How many items the chart shows. See Limit

Colors

New charts start with the workspace’s saved theme and colors. These inputs change them on one chart:

theme applies one of the chart themes, which sets the background, palette, fonts and grid together. The themes are classic, midnight, studio, broadsheet, neon, ember, financialLight, financialDark, pastel and code. Any of the color inputs below sent with theme change that part of the theme.
colorScheme is the palette for grouped charts, pie charts and heatmaps. Sending it without color also sets plain charts to the palette’s first color.
color is the single color that plain bar, line, area and scatter charts draw with. null uses the color scheme’s first color.
bgColor is the chart’s background color. null makes the background transparent, so the page behind an embedded chart shows through.
textColor is the main color for the title, subtitle, axis labels and legend. null goes back to the built in text colors. Text items with a color of their own in the editor keep that color.

Colors are hex values such as #1f77b4, #fff or #1f77b480, where the last two digits set the transparency. The chart in the response lists its current theme, colorScheme, color, bgColor and textColor. These are the same settings as the color and font panels in the editor.

Axis titles

Each axis is titled with its column name until the AI app sends a title of its own. The y axis title also names the aggregate, such as Sales (sum).

xTitle and yTitle replace the column name with your own text, up to 100 characters.
Send null for xTitle or yTitle to go back to the column name.
Send "" to hide the title on one axis.
showAxisTitles shows or hides the titles on both axes.

On a heatmap, yTitle titles the vertical axis, which shows the groupBy column. The chart in the response lists its current xTitle, yTitle and showAxisTitles, and a null title means the axis uses its column name. These are the same settings as Axis Titles in the editor.

Images

images draws images from the workspace’s shared assets on the chart, such as a company logo in a corner. Each image needs an assetId:

[{"assetId": "6f1c2d3e-...", "position": "bottomRight", "width": 80}]

Field	Description
`assetId`	The image, from `list_assets`, `import_asset_from_url` or an asset upload
`position`	`topLeft`, `topRight`, `bottomLeft`, `bottomRight` (default) or `center`
`width`	Width in pixels. The image keeps its shape. Without a width, the image takes up at most a fifth of the chart
`opacity`	0 to 100. 100 (default) is solid
`layer`	`over` (default) draws the image on top of the data, and `under` draws it behind the data, for a watermark

Sending images replaces every image on the chart, including images added in the editor, and null removes them all. A chart can have up to 10 images, and each one keeps its corner and shape when an embedded chart is resized. The chart in the response lists its images with their position and size in pixels. You can move or resize them later in the editor.

Limit

limit controls how many x values or series the chart shows. Charts made by an AI app start with every item showing, including the sheet’s first chart. For a top 5 chart, send:

{"mode": "top", "count": 5}

Field	Description
`mode`	`off` shows every item, `top` keeps `count` items, and `auto` keeps the 50 largest x values when there are more than 50
`count`	Items to keep, 1 to 999. Sending `count` on its own turns on `top`
`keep`	`largest` (default) or `smallest` values
`axis`	`x` (default) limits the x values, and `groupBy` limits the series of grouped and stacked charts
`groupOthers`	`true` combines the remaining items into one All Others item. Works on text columns

Auto Limit keeps the largest values, so on a Year or number x axis with more than 50 values it drops the smallest ones, which are often the earliest years. On update_chart, only the limit fields sent change. Gauge charts show a single value, so limit applies to the other chart types. These are the same settings as Limit Top Items in the editor.

Filters

filters is a list of filters, each on one column. A row has to pass every filter to appear in the chart. Each filter has a column, a condition and up to 5 values:

[
    {"column": "Country", "condition": "equals", "values": ["United States", "China", "India"]},
    {"column": "Year", "condition": "between", "values": [2000, 2020]}
]

Column type	Conditions
Text	`equals`, `notEqual`, `contains`, `notContains`, `startsWith`, `endsWith`
Number	`equals`, `notEqual`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`, `between`
Date	`equals`, `notEqual`, `before`, `after`, `between`
Every type	`blank`, `notBlank`, and `none` to remove the column’s filter

A row passes equals, contains, startsWith or endsWith when it matches any of the values.
A row passes notEqual or notContains when it matches none of the values.
Comparisons, before and after take one value, and between takes [from, to].
Dates are written as yyyy-mm-dd, and text matching ignores case.
Text values can be up to 2,000 characters each.

These are the same filters you can set on a chart in the InstaCharts editor, so you can review or change them there later. Read more about filtering chart data.

Chart types

`type`	Chart	Uses `groupBy`
`bar`	Bar Chart	No
`stackedBar`	Stacked Bar Chart	Yes
`groupedBar`	Grouped Bar Chart	Yes
`line`	Line Chart	No
`groupedLine`	Grouped Line Chart	Yes
`scatter`	Scatterplot Chart	No
`groupedScatter`	Grouped Scatterplot Chart	Yes
`area`	Area Chart	No
`groupedArea`	Grouped Area Chart	Yes
`pie`	Pie Chart	No
`radar`	Radar Chart	Yes
`heatmap`	Heatmap Chart	Yes
`mekko`	Mekko Chart	Yes
`gauge`	Gauge Chart	No
`groupedGauge`	Grouped Gauge Chart	Yes

Date grouping

dateGrouping applies to date columns on the x axis. year, quarter, month, week and day follow the timeline. monthOfYear and dayOfWeek combine every year into 12 months or 7 weekdays. When it isn’t set, dates spanning more than 5 years are grouped by year, and dates spanning 2 to 5 years are grouped by month.

update_chart

Changes an existing chart, including the sheet’s blank first chart. Only the fields sent are changed. It takes chartId plus any of the create_chart inputs. Send null for groupBy or y to clear it.

filters only changes the columns it names, and the chart’s other filters stay in place. Use the none condition to remove one column’s filter, or send null for filters to remove every filter. The chart in the response lists its current filters.

Input	Required	Description
`chartId`	Yes	The chart to change

share_chart

Makes a chart public and returns its share link (shareUrl), its embed URL and the iframe embed code. Anyone with the link can see the chart. Send active: false to make the chart private again.

Input	Required	Description
`chartId`	Yes	The chart to share
`active`	No	`true` shares the chart (default), `false` stops sharing

Read more about sharing charts and embedding charts in a website.

Asset tools

Asset tools add images, such as a company logo, to the workspace’s shared assets. These are the same images as the Shared Logos folder in the editor, so every sheet in the workspace can use them, and you can manage them as Shared Assets in Workspace Settings. Images can be PNG, JPG, BMP or WebP files up to 2 MB, and they count toward the workspace’s storage. To place an image on a chart, send its assetId in the chart’s images.

list_assets

Lists the images in a workspace’s shared assets with their assetId, name, width and height in pixels, and size in bytes. Listing assets is free.

Input	Required	Description
`workspaceId`	Yes	The workspace to list

import_asset_from_url

Downloads an image from a public link, such as the logo on your company’s website, into the workspace’s shared assets. The link has to point at the image file itself and use https://. Returns the new asset with its assetId.

Input	Required	Description
`workspaceId`	Yes	The workspace for the image
`url`	Yes	The `https://` address of the image
`name`	No	Asset name. Without one, the image takes the file’s name

create_asset_upload_link

Returns a one-time upload link (uploadUrl) that adds a local image file to the workspace’s shared assets. The file has to be sent within 15 minutes as an HTTP POST with multipart/form-data, with the file in a field named file:

curl -F "file=@logo.png" <uploadUrl>

The upload’s response is the new asset with its assetId. Each link works once. Creating the link is free, and the upload counts as one task. This tool needs an AI app that can send a file, such as one that can run commands (ex: Claude Code) or make HTTP requests.

Input	Required	Description
`workspaceId`	Yes	The workspace for the image
`name`	No	Asset name. Without one, the image takes the file’s name

Read more about image annotations in the editor.

Connect AI Apps with the MCP Server - set up Claude, ChatGPT and Claude Code
Tasks - how tasks are counted
All Chart Types - every chart InstaCharts can make