Smartsheet

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.

---

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

Option 1 — install from PyPI (recommended for end users)

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

Search

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.