SimpleKPI MCP server
38 operations0 webhooks
KPIs from SimpleKPI - create and manage KPIs, categories and units, write actuals and targets as entries one at a time or in bulk, read aggregated reports, and look up users, frequencies, icons and breakdowns.
Try SimpleKPI with your agent
Connect SimpleKPI, then paste this into Claude, ChatGPT or Cursor. For ideas from other apps, see the use cases.
Using Corsair, show me what you can do in SimpleKPI on my account, then run one read-only example and show me the result.
SimpleKPI tools and triggers
Tools are what your agent can do in SimpleKPI through Corsair's MCP server. Triggers are the SimpleKPI events a routine can start from.
Kpi Categories
- CreateWrite
Create a KPI category, which groups KPIs on the dashboard
kpiCategories.create
- DeleteDestructive
Delete a KPI category; the KPIs in it are affected and this cannot be undone
kpiCategories.delete
- GetRead-only
Read one KPI category by id, with its name and sort order
kpiCategories.get
- Kpis.CreateWrite
Create a KPI inside one category; it lands in the category in the path even when the body names another
kpiCategories.kpis.create
- Kpis.DeleteDestructive
Delete a KPI through its category, with every entry recorded against it; this cannot be undone
kpiCategories.kpis.delete
- Kpis.GetRead-only
Read one KPI through its category. A KPI under a different category answers 404
kpiCategories.kpis.get
- Kpis.ListRead-only
List the KPIs inside one category
kpiCategories.kpis.list
- Kpis.UpdateWrite
Replace a KPI through its category. Anything left out is reset to its default
kpiCategories.kpis.update
- ListRead-only
List the KPI categories on the account
kpiCategories.list
- UpdateWrite
Replace a KPI category; anything left out is reset to its default
kpiCategories.update
Kpi Entries
- CreateWrite
Write or update one KPI entry. kpi_id, source_id and entry_date identify it, so the same trio again updates rather than duplicating. A write with every value empty answers stored: false
kpiEntries.create
- Create BatchWrite
Write many KPI entries in one request. It answers 200 even when every row was rejected, so rows_added is the only signal; a batch that stored nothing throws
kpiEntries.createBatch
- DeleteDestructive
Delete one KPI entry; this cannot be undone
kpiEntries.delete
- GetRead-only
Read one KPI entry by id, with its actual, target and notes
kpiEntries.get
- ListRead-only
List KPI entries, filtered by user, KPI, breakdown source and date range; narrow by KPI and dates or the response gets large
kpiEntries.list
- UpdateWrite
Change one KPI entry named in the path; the setActual, setTarget and setNotes flags choose which values are written
kpiEntries.update
Breakdown Items
- CreateWrite
Create a breakdown item, such as a person, team, product or region; its id is what an entry sends as source_id
breakdownItems.create
- DeleteDestructive
Delete a breakdown item. SimpleKPI answers 204 but keeps the item archived (is_archived true) rather than removing it
breakdownItems.delete
- GetRead-only
Read one breakdown item by id, with the breakdown it belongs to
breakdownItems.get
- ListRead-only
List the breakdown items a KPI can be broken down by, a page at a time; the API has no breakdown filter, so filter on breakdown_id across the pages
breakdownItems.list
- UpdateWrite
Replace a breakdown item; anything left out is reset to its default
breakdownItems.update
Kpi Units
- CreateWrite
Create a KPI unit with a numeric entry format and a display format
kpiUnits.create
- DeleteDestructive
Delete a KPI unit; KPIs using it are affected, and this cannot be undone
kpiUnits.delete
- GetRead-only
Read one KPI unit by id, with its entry and display formats
kpiUnits.get
- ListRead-only
List the units a KPI can use, with their entry and display formats
kpiUnits.list
- UpdateWrite
Replace a KPI unit; anything left out is reset to its default
kpiUnits.update
Kpis
- CreateWrite
Create a KPI. icon_id and unit_id must be real ids from kpiIcons and kpiUnits even though the contract does not mark them mandatory
kpis.create
- DeleteDestructive
Delete a KPI and every entry recorded against it; this cannot be undone
kpis.delete
- GetRead-only
Read one KPI by id, with its frequency, unit, icon, value direction and aggregate function
kpis.get
- ListRead-only
List the KPIs on the account with their frequency, unit, icon, value direction and aggregate function; page until a page comes back short
kpis.list
- UpdateWrite
Replace a KPI wholesale. Anything left out is reset to its default rather than kept, so read it first and send it back changed
kpis.update
Kpi Frequencies
- GetRead-only
Read one KPI frequency by its id, such as W for weekly
kpiFrequencies.get
- ListRead-only
List the frequencies a KPI can use: D daily, W weekly, M monthly, Q quarterly, Y yearly
kpiFrequencies.list
Kpi Icons
- GetRead-only
Read one KPI icon by id, which is what a KPI sends as icon_id
kpiIcons.get
- ListRead-only
List the icons a KPI can use, which is where a valid icon_id comes from
kpiIcons.list
Users
- GetRead-only
Read one user by id, which is what an entry sends as user_id
users.get
- ListRead-only
List the people on the account with their role and status; read-only, because people are added in the app
users.list
Reports
- All Data EntriesRead-only
Read actuals and targets as one row per KPI, breakdown source and period, already aggregated to each KPI's own frequency
reports.allDataEntries
Connect SimpleKPI to Claude, ChatGPT or Cursor
- 1
Connect SimpleKPI in Corsair
Add your SimpleKPI API key once in Corsair. Corsair stores the credential encrypted and makes the SimpleKPI API calls for your agent, so it never goes into a prompt or a config file. Connect SimpleKPI
If your link lets the agent add apps, you can skip this: it gives you a sign-in link the first time it needs SimpleKPI. On a ChatGPT personal plan, connect SimpleKPI here first.
- 2
Add Corsair's MCP server to your agent
Every client uses the same address:
https://mcp.corsair.dev/mcpOpen Customize → Connectors → Add custom connector, paste the address, then select Connect.Add a custom MCP server with the address and choose OAuth. Personal plans get read tools only.Add to CursorOr add this to~/.cursor/mcp.json. Cursor opens Corsair to sign in the first time it connects.{ "mcpServers": { "corsair": { "url": "https://mcp.corsair.dev/mcp" } } }Run this, then run/mcpin Claude Code to sign in.claude mcp add --transport http corsair https://mcp.corsair.dev/mcpCodex, Gemini CLI, VS Code, Zed and other clients with OAuth sign-in work the same way. Clients without it, such as GitHub Copilot's coding agent, use a link's own address and an API key. Setup for every client
- 3
Sign in and choose what needs your approval
Your client opens Corsair to sign in. Pick a link: the apps your agent can use and a mode that decides what it may do without asking. In the default Cautious mode, SimpleKPI's read and write operations run right away and its 6 destructive operations wait for your approval. Strict mode asks before every write and refuses destructive operations, and Read mode allows reads only.
FAQ
Install corsair and @corsair-dev/simplekpi, add the SimpleKPI plugin, and connect with an API key. Then call methods like corsair.simplekpi.api.breakdownItems.create() from your app. Corsair keeps each tenant isolated.
Yes. SimpleKPI requires an API key from your SimpleKPI account or developer dashboard. Create credentials with access that matches what you automate, then paste them into Corsair or connect through managed auth in Hub.
Yes. One Corsair client can hit SimpleKPI, GitHub, Notion, Stripe, and the rest. Trigger SimpleKPI from a webhook, push updates to Slack, or chain actions across plugins. Same tenant context across integrations, plain TypeScript.
Teams use Corsair for KPIs from SimpleKPI - create and manage KPIs, categories and units, write actuals and targets as entries one at a time or in bulk, read aggregated reports, and look up users, frequencies, icons and breakdowns. Common builds include sync jobs, admin tooling, and agents that call SimpleKPI APIs from your backend.
The SDK is open source. Self-host and you pay Corsair nothing for the integration layer. Hub bills for hosted auth and execution, not per SimpleKPI API call. Hub has a generous free tier. For hobby projects you can probably run the whole thing on free. Paid plans start to matter with more tenants or heavier traffic.
We maintain @corsair-dev/simplekpi in the open repo. When SimpleKPI ships API changes, upgrade the package. Your call sites stay typed. You should not need to rewrite the integration layer each time.
No. Corsair does not read your SimpleKPI data or hold individual access credentials. Credentials stay in your database. API calls run on your instance. We do not store SimpleKPI data on your behalf.
Yes. Add https://mcp.corsair.dev/mcp as a custom connector or MCP server in Claude, ChatGPT, Cursor, VS Code, Claude Code, Codex or any client that supports remote MCP servers with OAuth sign-in, then sign in to Corsair. On ChatGPT personal plans, custom servers currently get read tools only.
Yes. Put SimpleKPI on a link in Strict mode and every write waits for your approval, while destructive actions are refused. The default Cautious mode asks only before the 6 destructive SimpleKPI operations. You can change a link's mode at hub.corsair.dev/me.