Connect your steps

steps-mcp is a Model Context Protocol server that gives an AI assistant read-only access to your step history. It runs locally on your own machine and talks to the StepsMCP API using a personal key you generate.

Prerequisites

Node.js 20 or newer
A StepsMCP Pro subscription (purchased in the iOS app)
An API key from your dashboard

There's no install step — npx fetches the package on demand.

Set up your client

Claude Desktop

Settings → Developer → Edit Config (claude_desktop_config.json)

{
  "mcpServers": {
    "steps": {
      "command": "npx",
      "args": [
        "-y",
        "steps-mcp"
      ],
      "env": {
        "STEPS_MCP_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Run this in your terminal

claude mcp add steps --env STEPS_MCP_API_KEY=sk_live_your_key_here -- npx -y steps-mcp

Cursor

~/.cursor/mcp.json for all projects, or .cursor/mcp.json in one project

{
  "mcpServers": {
    "steps": {
      "command": "npx",
      "args": [
        "-y",
        "steps-mcp"
      ],
      "env": {
        "STEPS_MCP_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json in your workspace

{
  "servers": {
    "steps": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "steps-mcp"
      ],
      "env": {
        "STEPS_MCP_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Note the key is `servers`, not `mcpServers`.

Using ChatGPT?

ChatGPT can't connect to StepsMCP today. Its MCP support reaches only remote servers over HTTP or SSE — it runs in the cloud and can't launch a local command. StepsMCP runs locally on your own machine, which is what keeps your health data off our servers beyond your own account. Supporting ChatGPT would mean hosting a remote endpoint, which we may add later.

Available tools

All three tools are read-only. Nothing in this server can modify or delete your data.

Tool	Arguments	Returns
`get_daily_steps`	`date`	Step count for a single day.
`get_steps_range`	`start_date, end_date`	Step counts for each day across a date range, with totals.
`get_steps_summary`	`period`	Total, average and best day for the last week or month, plus the trend against the previous period.

Try asking

“How many steps did I take on August 3rd?”
“Chart my daily steps for the first two weeks of August.”
“Am I walking more this month than last month?”
“What day of the week do I walk the least? Look at the last month.”

About your key

The key is tied to your StepsMCP account. It is shown once, at creation, and stored only as a hash — we cannot recover it for you.
Revoke or rotate it any time from your dashboard. Revocation takes effect on the very next request.
Keys are read-only and rate-limited to 60 requests per minute.
If your Pro subscription lapses, the key stops working until you resubscribe.

Troubleshooting

Message	Fix
`STEPS_MCP_API_KEY is not set`	The env block is missing from your config. Compare against the snippet for your client above.
Your API key was rejected	The key was revoked or mistyped. Generate a new one on your dashboard.
Pro subscription required	Your subscription lapsed. Resubscribe in the iOS app; the same key starts working again.
Rate limit exceeded	More than 60 requests in a minute. Wait a minute and retry.