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

Other clients

Any tool that can launch a local stdio MCP server works, even if it isn't listed above. Use this same shape — most clients read it directly, or expect the equivalent in their own config file.

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

Building your own client, or running the server somewhere unusual (a container, a different host)? Set STEPS_MCP_API_URL alongside STEPS_MCP_API_KEY to point it at a different base URL — this defaults to https://www.stepsmcp.com and normally doesn't need to be set. If you do set it, use the www. host: the bare domain redirects to it, and that redirect strips the Authorization header, which fails with a confusing “missing API key” error even though your key is correct.

Remote clients (Claude.ai, ChatGPT)

ChatGPT and Claude.ai's web connector don't run a local command — they connect to a URL and sign in over OAuth in the browser. Use the remote URL below instead of the snippets above.

https://www.stepsmcp.com/api/mcp

Paste that into the client's “Add custom connector” / “Custom MCP Server URL” field. It'll redirect you to sign in with your StepsMCP account and approve the connection — no key to copy or paste.

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.