Skip to main content
Glama

smartsheet-mcp

CI PyPI version Python versions License: MIT

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

  1. Get a Smartsheet API access token — see Getting an API key.

  2. Install the server — see Install.

  3. Configure it — export SMARTSHEET_ACCESS_TOKEN or put it in a .env file.

  4. 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.

  1. Sign in to Smartsheet.

  2. In the bottom-left corner, click Account → Personal Settings.

  3. Open the API Access tab.

  4. Click Generate new access token, give it a descriptive name, and confirm.

  5. Copy the token immediately — Smartsheet will only show it to you once.

  6. Store it somewhere safe (a password manager or secret store). You will paste it into an environment variable or .env file, 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)

https://api.smartsheet.com/2.0

EU

https://api.smartsheet.eu/2.0

Australia

https://api.smartsheet.au/2.0

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:

  1. Return to Account → Personal Settings → API Access.

  2. Click the ⋯ menu next to the token and choose Revoke.

  3. Generate a new one and update every place that uses it.


Install

Requires Python 3.10+.

pip install smartsheet-mcp

Or with pipx to keep it isolated:

pipx install smartsheet-mcp

Either 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

SMARTSHEET_ACCESS_TOKEN

✅

—

Bearer token from the steps above

SMARTSHEET_API_BASE_URL

❌

https://api.smartsheet.com/2.0

Override for EU/AU regions

SMARTSHEET_TIMEOUT

❌

30

HTTP timeout in seconds

SMARTSHEET_LOG_LEVEL

❌

INFO

DEBUG / INFO / WARNING / ERROR

Option A — environment variable

export SMARTSHEET_ACCESS_TOKEN="paste-your-token-here"
smartsheet-mcp

Option 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.py

Register 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), or

  • Global: ~/.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.json

Minimal 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

smartsheet_server_info

GET /serverinfo

smartsheet_get_user_me

GET /users/me

Sheets, columns, rows, cells

Tool

Endpoint

smartsheet_list_sheets

GET /sheets

smartsheet_get_sheet

GET /sheets/{id}

smartsheet_list_columns

GET /sheets/{id}/columns

smartsheet_get_row

GET /sheets/{id}/rows/{rowId}

smartsheet_get_sheet_version

GET /sheets/{id}/version

smartsheet_get_sheet_publish

GET /sheets/{id}/publish

smartsheet_get_cell_history

GET /sheets/{id}/rows/{rowId}/columns/{colId}/history

Sheet summary

Tool

Endpoint

smartsheet_get_sheet_summary

GET /sheets/{id}/summary

smartsheet_list_summary_fields

GET /sheets/{id}/summary/fields

Tool

Endpoint

smartsheet_search

GET /search

smartsheet_search_in_sheet

GET /search/sheets/{id}

Workspaces

Tool

Endpoint

smartsheet_list_workspaces

GET /workspaces

smartsheet_get_workspace

GET /workspaces/{id}

smartsheet_get_workspace_metadata

GET /workspaces/{id}/metadata

smartsheet_list_workspace_children

GET /workspaces/{id}/children (token-paginated)

Folders

Tool

Endpoint

smartsheet_list_personal_folders

GET /folders/personal

smartsheet_get_folder

GET /folders/{id}

smartsheet_get_folder_metadata

GET /folders/{id}/metadata

smartsheet_list_folder_children

GET /folders/{id}/children (token-paginated)

Reports

Tool

Endpoint

smartsheet_list_reports

GET /reports

smartsheet_get_report

GET /reports/{id}

smartsheet_get_report_publish

GET /reports/{id}/publish

Dashboards (Sights)

Tool

Endpoint

smartsheet_list_dashboards

GET /sights

smartsheet_get_dashboard

GET /sights/{id}

smartsheet_get_dashboard_publish

GET /sights/{id}/publish

Discussions & comments

Tool

Endpoint

smartsheet_list_sheet_discussions

GET /sheets/{id}/discussions

smartsheet_get_discussion

GET /sheets/{id}/discussions/{id}

smartsheet_list_row_discussions

GET /sheets/{id}/rows/{rowId}/discussions

smartsheet_list_discussion_attachments

GET /sheets/{id}/discussions/{id}/attachments

smartsheet_get_comment

GET /sheets/{id}/comments/{id}

Attachments

Tool

Endpoint

smartsheet_list_sheet_attachments

GET /sheets/{id}/attachments

smartsheet_list_row_attachments

GET /sheets/{id}/rows/{rowId}/attachments

smartsheet_list_comment_attachments

GET /sheets/{id}/comments/{id}/attachments

smartsheet_get_attachment

GET /sheets/{id}/attachments/{id}

smartsheet_list_attachment_versions

GET /sheets/{id}/attachments/{id}/versions

Users, groups, contacts, alternate emails

Tool

Endpoint

smartsheet_list_users

GET /users

smartsheet_get_user

GET /users/{id}

smartsheet_list_groups

GET /groups

smartsheet_get_group

GET /groups/{id}

smartsheet_list_contacts

GET /contacts

smartsheet_get_contact

GET /contacts/{id}

smartsheet_list_alternate_emails

GET /users/{id}/alternateemails

smartsheet_get_alternate_email

GET /users/{id}/alternateemails/{altId}

Sharing

Tool

Endpoint

smartsheet_list_shares

GET /{scope}/{id}/shares (sheets, reports, workspaces, sights)

smartsheet_get_share

GET /{scope}/{id}/shares/{shareId}

Automation & cross-sheet references

Tool

Endpoint

smartsheet_list_automation_rules

GET /sheets/{id}/automationrules

smartsheet_get_automation_rule

GET /sheets/{id}/automationrules/{id}

smartsheet_list_cross_sheet_references

GET /sheets/{id}/crosssheetreferences

smartsheet_get_cross_sheet_reference

GET /sheets/{id}/crosssheetreferences/{id}

Update requests

Tool

Endpoint

smartsheet_list_update_requests

GET /sheets/{id}/updaterequests

smartsheet_get_update_request

GET /sheets/{id}/updaterequests/{id}

smartsheet_list_sent_update_requests

GET /sheets/{id}/sentupdaterequests

smartsheet_get_sent_update_request

GET /sheets/{id}/sentupdaterequests/{id}

Webhooks & proofs

Tool

Endpoint

smartsheet_list_webhooks

GET /webhooks

smartsheet_get_webhook

GET /webhooks/{id}

smartsheet_list_proofs

GET /sheets/{id}/proofs

smartsheet_get_proof

GET /sheets/{id}/proofs/{id}

smartsheet_list_proof_attachments

GET /sheets/{id}/proofs/{id}/attachments

smartsheet_list_proof_discussions

GET /sheets/{id}/proofs/{id}/discussions

smartsheet_list_proof_request_actions

GET /sheets/{id}/proofs/{id}/requestactions

Templates & favorites

Tool

Endpoint

smartsheet_list_templates

GET /templates

smartsheet_list_public_templates

GET /templates/public

smartsheet_list_favorites

GET /favorites

smartsheet_get_favorite

GET /favorites/{type}/{id}


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, favorites

Troubleshooting

Symptom

Likely cause

RuntimeError: SMARTSHEET_ACCESS_TOKEN is not set

Export the variable or create .env.

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 *_children

max_items must be 100..1000 and a multiple of 100; don't use page_size here.

Kiro doesn't see the server

Check mcp.json path; restart Kiro; confirm smartsheet-mcp --help works in the same shell.


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_events once a test account with the premium add-on is available.

  • Recorded API fixtures + automated pytest suite.


License

MIT.

Available Tools

66 tools
smartsheet_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_shareC

Get a single share on a resource.

Inputs: scope (required), share_id (required), resource_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_sharesB

List shares for a sheet/report/workspace/dashboard.

Inputs: scope (required), resource_id (required), page, page_size, +2 more.

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_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

    C2.7/5.0

    Scored across 66 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count1/5

    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).

    Completeness1/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides 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
    • A
      license
      A
      quality
      D
      maintenance
      Enables executing SQL queries, exploring database schemas, and exporting results from Redash via MCP, with ad-hoc queries and write protection.
      5
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Read-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
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.
      -