smartsheet-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smartsheet-mcp list all my sheets"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
smartsheet-mcp
A Model Context Protocol server that exposes Smartsheet read APIs as MCP tools, so you can browse and query Smartsheet data from any MCP-compatible client (for example, Kiro).
Status: read-only, 66 tools covering the Smartsheet read surface. Write operations (add/update/delete rows, create sheets, register webhooks, etc.) are not implemented — this server is intentionally safe for exploration and reporting workflows.
Quick start
Get a Smartsheet API access token — see Getting an API key.
Install the server — see Install.
Configure it — export
SMARTSHEET_ACCESS_TOKENor put it in a.envfile.Register with your MCP client — see Register with Kiro.
Related MCP server: @arkty/redash-mcp
Getting an API key
The Smartsheet API uses a bearer access token.
Requirement: your Smartsheet account must be on a Business or Enterprise plan. Free / Pro plans cannot access the public API.
Sign in to Smartsheet.
In the bottom-left corner, click Account → Personal Settings.
Open the API Access tab.
Click Generate new access token, give it a descriptive name, and confirm.
Copy the token immediately — Smartsheet will only show it to you once.
Store it somewhere safe (a password manager or secret store). You will paste it into an environment variable or
.envfile, not into source control.
Smartsheet's own walkthrough, with screenshots: https://help.smartsheet.com/articles/2482389-generate-API-key.
Regional endpoints
If your Smartsheet account lives outside the US, override the base URL:
Region | Base URL |
US (default) |
|
EU |
|
Australia |
|
Set it with SMARTSHEET_API_BASE_URL.
Rotating or revoking a token
If a token is leaked (committed to git, pasted in a chat, etc.) revoke it immediately:
Return to Account → Personal Settings → API Access.
Click the ⋯ menu next to the token and choose Revoke.
Generate a new one and update every place that uses it.
Install
Requires Python 3.10+.
Option 1 — install from PyPI (recommended for end users)
pip install smartsheet-mcpOr with pipx to keep it isolated:
pipx install smartsheet-mcpEither way, the smartsheet-mcp command is now on your PATH.
Option 2 — editable install from source (for contributors)
git clone https://github.com/Kcrong/smartsheet-mcp.git
cd smartsheet-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .Option 3 — with uv
# Run without installing, one-off
uvx smartsheet-mcp --version
# Or develop from source
git clone https://github.com/Kcrong/smartsheet-mcp.git
cd smartsheet-mcp
uv venv
source .venv/bin/activate
uv pip install -e .After install, smartsheet-mcp is on your PATH and
python -m smartsheet_mcp works too.
Configure
The server reads all configuration from environment variables.
Variable | Required | Default | Notes |
| ✅ | — | Bearer token from the steps above |
| ❌ |
| Override for EU/AU regions |
| ❌ |
| HTTP timeout in seconds |
| ❌ |
|
|
Option A — environment variable
export SMARTSHEET_ACCESS_TOKEN="paste-your-token-here"
smartsheet-mcpOption B — .env file (good for local development)
Copy the template and fill it in:
cp .env.example .env
# edit .env and set SMARTSHEET_ACCESS_TOKEN.env is already listed in .gitignore.
Smoke test
smartsheet-mcp --help
smartsheet-mcp --version
# Start the server (stdio; it will wait for MCP messages from a client)
SMARTSHEET_ACCESS_TOKEN=... smartsheet-mcp
# Ctrl+C to stop.An end-to-end check against a real token:
# Print a few sample rows from one accessible sheet
SMARTSHEET_ACCESS_TOKEN=... python scripts/show_sheet_sample.py
# Call every registered tool (read-only)
SMARTSHEET_ACCESS_TOKEN=... python scripts/live_read_all.pyRegister with Kiro
Kiro reads MCP server configuration from either:
Project-local:
.kiro/settings/mcp.json(checked into your project, but this file is gitignored in this repo to avoid leaking tokens), orGlobal:
~/.kiro/settings/mcp.json(recommended for personal tokens).
This repo ships .kiro/settings/mcp.example.json as a starting point. Copy
it and fill in the real values:
cp .kiro/settings/mcp.example.json .kiro/settings/mcp.json
# edit .kiro/settings/mcp.jsonMinimal example entry (point command at the interpreter inside your venv):
{
"mcpServers": {
"smartsheet": {
"command": "/absolute/path/to/smartsheet-mcp/.venv/bin/python",
"args": ["-m", "smartsheet_mcp"],
"env": {
"SMARTSHEET_ACCESS_TOKEN": "paste-your-token-here"
},
"timeout": 120000
}
}
}If you installed the project so that smartsheet-mcp is on Kiro's PATH:
{
"mcpServers": {
"smartsheet": {
"command": "smartsheet-mcp",
"env": {
"SMARTSHEET_ACCESS_TOKEN": "paste-your-token-here"
},
"timeout": 120000
}
}
}Restart Kiro (or reload MCP servers) after editing the config. Confirm the
server is live by asking Kiro to call smartsheet_get_user_me or
smartsheet_list_sheets.
Security notes for the config file
Never commit
.kiro/settings/mcp.json. It is already in.gitignore; keep it that way.Prefer Kiro's global config (
~/.kiro/settings/mcp.json) for personal tokens so they never appear inside a project checkout.For shared/CI use, consider an OAuth-issued service token on a dedicated Smartsheet account rather than a developer's personal token.
Available tools (66)
All tools are prefixed smartsheet_.
Meta
Tool | Endpoint |
|
|
|
|
Sheets, columns, rows, cells
Tool | Endpoint |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sheet summary
Tool | Endpoint |
|
|
|
|
Search
Tool | Endpoint |
|
|
|
|
Workspaces
Tool | Endpoint |
|
|
|
|
|
|
|
|
Folders
Tool | Endpoint |
|
|
|
|
|
|
|
|
Reports
Tool | Endpoint |
|
|
|
|
|
|
Dashboards (Sights)
Tool | Endpoint |
|
|
|
|
|
|
Discussions & comments
Tool | Endpoint |
|
|
|
|
|
|
|
|
|
|
Attachments
Tool | Endpoint |
|
|
|
|
|
|
|
|
|
|
Users, groups, contacts, alternate emails
Tool | Endpoint |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sharing
Tool | Endpoint |
|
|
|
|
Automation & cross-sheet references
Tool | Endpoint |
|
|
|
|
|
|
|
|
Update requests
Tool | Endpoint |
|
|
|
|
|
|
|
|
Webhooks & proofs
Tool | Endpoint |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Templates & favorites
Tool | Endpoint |
|
|
|
|
|
|
|
|
Project layout
smartsheet-mcp/
├── pyproject.toml
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── .env.example
├── .gitignore
├── .kiro/settings/mcp.example.json # template; the real mcp.json is gitignored
├── scripts/
│ ├── live_read_all.py # calls every tool with a real token
│ └── show_sheet_sample.py # prints a sample sheet as a table
└── src/smartsheet_mcp/
├── __init__.py
├── __main__.py # python -m smartsheet_mcp
├── server.py # MCP stdio server
├── client.py # Async Smartsheet HTTP client (httpx)
├── config.py # Env-var settings
├── errors.py # Typed exceptions
└── tools/
├── __init__.py # Tool catalog + dispatcher (66 tools)
├── _common.py
├── meta.py
├── sheets.py
├── cells.py
├── summary.py
├── search.py
├── workspaces.py
├── folders.py
├── structure.py # metadata/children/version/publish/in-sheet search
├── reports.py
├── dashboards.py
├── discussions.py
├── attachments.py
├── users.py
├── sharing.py
├── automation.py
├── cross_sheet.py
├── update_requests.py
├── webhooks.py
├── proofs.py
└── extras.py # templates, favoritesTroubleshooting
Symptom | Likely cause |
| Export the variable or create |
HTTP 401 on every call | Token is invalid, revoked, or from the wrong region. Verify in the Smartsheet UI. |
HTTP 403 errorCode 1004 | Your plan does not include this feature (e.g. Events Reporting is Enterprise-only). |
HTTP 400 errorCode 2238 on |
|
Kiro doesn't see the server | Check |
Roadmap
Write operations are deliberately out of scope for v0.x. Candidate follow-ups:
Write tools: add/update/delete rows, update cells.
Sheet create/copy/move/delete, column add/update/delete.
Attachments upload/delete/download binary.
Discussions/comments create/update/delete.
Webhooks register/enable/delete, event callbacks.
Automation rules / update requests create & modify.
list_eventsonce a test account with the premium add-on is available.Recorded API fixtures + automated pytest suite.
License
MIT.
Available Tools
66 toolssmartsheet_get_alternate_emailB
Get a single alternate email for a user.
Inputs: user_id (required), alternate_email_id (required).
smartsheet_get_attachmentB
Get an attachment's metadata and temporary download URL.
Inputs: sheet_id (required), attachment_id (required).
smartsheet_get_automation_ruleC
Get a single automation rule.
Inputs: rule_id (required), sheet_id (required).
smartsheet_get_cell_historyB
Get the change history of a single cell (row x column).
Inputs: row_id (required), sheet_id (required), column_id (required), page, +3 more.
smartsheet_get_commentC
Get a single comment.
Inputs: sheet_id (required), comment_id (required).
smartsheet_get_contactC
Get a single contact.
Inputs: contact_id (required).
smartsheet_get_cross_sheet_referenceB
Get a single cross-sheet reference.
Inputs: sheet_id (required), reference_id (required).
smartsheet_get_dashboardC
Get a dashboard (with its widgets).
Inputs: dashboard_id (required).
smartsheet_get_dashboard_publishB
Get a dashboard's publish settings.
Inputs: dashboard_id (required).
smartsheet_get_discussionC
Get a single discussion with comments.
Inputs: sheet_id (required), discussion_id (required).
smartsheet_get_favoriteC
Check whether a specific item is favorited.
Inputs: favorite_id (required), favorite_type (required).
smartsheet_get_folderC
Get a folder and its contents.
Inputs: folder_id (required), include.
smartsheet_get_folder_metadataD
Lightweight metadata for a folder.
Inputs: folder_id (required).
smartsheet_get_groupC
Get a single group (includes members).
Inputs: group_id (required).
smartsheet_get_proofC
Get a single proof.
Inputs: proof_id (required), sheet_id (required).
smartsheet_get_reportC
Get a report with columns/rows.
Inputs: report_id (required), page, level, include, +1 more.
smartsheet_get_report_publishB
Get a report's publish settings.
Inputs: report_id (required).
smartsheet_get_rowC
Get a specific row from a sheet.
Inputs: row_id (required), sheet_id (required), level, exclude, +1 more.
smartsheet_get_sent_update_requestC
Get a single sent update request.
Inputs: sheet_id (required), sent_update_request_id (required).
smartsheet_get_sheetA
Get a sheet's full contents (columns + rows + cells). Use pagination for large sheets.
Inputs: sheet_id (required), page, level, exclude, +5 more.
smartsheet_get_sheet_publishB
Get a sheet's publish settings.
Inputs: sheet_id (required).
smartsheet_get_sheet_summaryB
Get a sheet's summary (all custom summary fields).
Inputs: sheet_id (required), exclude, include.
smartsheet_get_sheet_versionA
Get a sheet's current version number (lightweight).
Inputs: sheet_id (required).
smartsheet_get_update_requestC
Get a single update request.
Inputs: sheet_id (required), update_request_id (required).
smartsheet_get_userC
Get a single user.
Inputs: user_id (required).
smartsheet_get_user_meA
Get the currently authenticated Smartsheet user's profile.
Inputs: no named parameters.
smartsheet_get_webhookB
Get a single webhook.
Inputs: webhook_id (required).
smartsheet_get_workspaceB
Get a workspace and its top-level contents.
Inputs: workspace_id (required), include, load_all.
smartsheet_get_workspace_metadataC
Lightweight metadata for a workspace.
Inputs: workspace_id (required).
smartsheet_list_alternate_emailsC
List a user's alternate email addresses (Enterprise feature).
Inputs: user_id (required), page, page_size, include_all.
smartsheet_list_attachment_versionsC
List version history of an attachment.
Inputs: sheet_id (required), attachment_id (required), page, page_size, +1 more.
smartsheet_list_automation_rulesC
List automation rules on a sheet.
Inputs: sheet_id (required), page, page_size, include_all.
smartsheet_list_columnsB
List columns defined on a sheet.
Inputs: sheet_id (required), page, page_size, include_all.
smartsheet_list_comment_attachmentsC
List attachments on a comment.
Inputs: sheet_id (required), comment_id (required), page, page_size, +1 more.
smartsheet_list_contactsB
List the authenticated user's Smartsheet contacts.
Inputs: page, page_size, include_all.
smartsheet_list_cross_sheet_referencesC
List cross-sheet references on a sheet.
Inputs: sheet_id (required), page, page_size, include_all.
smartsheet_list_dashboardsC
List dashboards (Sights) the user can access.
Inputs: page, page_size, include_all, modified_since.
smartsheet_list_discussion_attachmentsC
List attachments under a discussion.
Inputs: sheet_id (required), discussion_id (required), page, page_size, +1 more.
smartsheet_list_favoritesB
List the user's favorite items.
Inputs: page, page_size, include_all.
smartsheet_list_folder_childrenA
Paginated child items of a folder. Uses token-based pagination: max_items must be 100..1000 (multiple of 100).
Inputs: folder_id (required), include, max_items, page_token.
smartsheet_list_groupsC
List groups in the user's account.
Inputs: page, page_size, include_all.
smartsheet_list_personal_foldersA
List the top-level items in the user's Home.
Inputs: no named parameters.
smartsheet_list_proof_attachmentsC
List attachments on a proof.
Inputs: proof_id (required), sheet_id (required), page, page_size, +1 more.
smartsheet_list_proof_discussionsC
List discussions on a proof.
Inputs: proof_id (required), sheet_id (required), page, page_size, +1 more.
smartsheet_list_proof_request_actionsC
List proof request action history.
Inputs: proof_id (required), sheet_id (required), page, page_size, +1 more.
smartsheet_list_proofsC
List proofs on a sheet.
Inputs: sheet_id (required), page, page_size, include_all.
smartsheet_list_public_templatesC
List Solution Center public templates.
Inputs: page, page_size, include_all.
smartsheet_list_reportsC
List reports the user can access.
Inputs: page, page_size, include_all, modified_since.
smartsheet_list_row_attachmentsC
List attachments on a row.
Inputs: row_id (required), sheet_id (required), page, page_size, +1 more.
smartsheet_list_row_discussionsC
List discussions on a specific row.
Inputs: row_id (required), sheet_id (required), page, include, +2 more.
smartsheet_list_sent_update_requestsB
List already-sent update requests on a sheet.
Inputs: sheet_id (required), page, page_size, include_all.
smartsheet_list_sheet_attachmentsC
List all attachments on a sheet.
Inputs: sheet_id (required), page, page_size, include_all.
smartsheet_list_sheet_discussionsC
List all discussions on a sheet.
Inputs: sheet_id (required), page, include, page_size, +1 more.
smartsheet_list_sheetsC
List sheets the authenticated user has access to.
Inputs: page, page_size, include_all, modified_since.
smartsheet_list_summary_fieldsC
List a sheet's summary fields with pagination.
Inputs: sheet_id (required), page, exclude, include, +2 more.
smartsheet_list_templatesC
List the user's custom templates.
Inputs: page, page_size, include_all.
smartsheet_list_update_requestsB
List pending update requests on a sheet.
Inputs: sheet_id (required), page, page_size, include_all.
smartsheet_list_usersA
List users in the authenticated user's account (admin rights may be required).
Inputs: page, emails, page_size, include_all.
smartsheet_list_webhooksA
List webhooks registered by the authenticated token.
Inputs: page, page_size, include_all.
smartsheet_list_workspace_childrenA
Paginated child items (folders/sheets/reports/dashboards/templates) of a workspace. Uses token-based pagination: max_items must be 100..1000 (multiple of 100).
Inputs: workspace_id (required), include, max_items, page_token.
smartsheet_list_workspacesB
List workspaces the user can access.
Inputs: page, page_size, include_all.
smartsheet_searchC
Search across all Smartsheet items the user can access.
Inputs: query (required), scopes, include, location, +1 more.
smartsheet_search_in_sheetC
Search within a single sheet only.
Inputs: query (required), sheet_id (required).
smartsheet_server_infoA
Get Smartsheet server information (formats, feature flags). Useful as a connectivity / auth smoke test.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 66 tools
Each tool targets a distinct resource and action (get vs list, or specific sub-resource), with no overlapping purposes. For example, smartsheet_get_sheet and smartsheet_get_sheet_publish are clearly separate concerns.
All tools follow a consistent smartsheet_verb_noun pattern (e.g., smartsheet_get_sheet, smartsheet_list_sheets, smartsheet_search), making the set predictable and easy to navigate.
With 66 tools, the count is extremely high, far exceeding the typical well-scoped range. While Smartsheet is a large platform, this many tools risks overwhelming agents, and many could be consolidated (e.g., merging get/list for sub-resources).
The tool set is severely incomplete for a full Smartsheet interface: it only includes read-only operations (get, list, search). There are no create, update, or delete tools, leaving agents unable to modify any data, which is a critical gap.
Maintenance
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Read-only discovery of ChatGXT's integration catalog and public MCP capabilities.
Read-only MCP over your Excel or Airtable plus the PDFs beside it, joined as one relational dataset.
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceProvides read-only access to TrustLayer's public API, enabling users to query and retrieve data about parties, documents, projects, and other TrustLayer entities through MCP-compatible tools.MIT
- AlicenseAqualityDmaintenanceEnables executing SQL queries, exploring database schemas, and exporting results from Redash via MCP, with ad-hoc queries and write protection.512 npmMIT
- AlicenseNot gradedqualityCmaintenanceRead-only MCP server for Quickbase that enables natural-language queries, schema exploration, data export, and saved report execution by auto-scanning app metadata and sample data on startup.MIT
- FlicenseNot gradedqualityDmaintenanceEnables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.-