netweft-mcp
v0.1.1
Published
Connect any stdio MCP client (Claude Desktop, Cursor, Windsurf...) to netweft's MCP server with an API key.
Downloads
706
Maintainers
Readme
netweft-mcp
Connect any MCP client to netweft, so an AI agent can read your SEO workspace: projects, saved keywords, rank tracking, site audits, project context and billing.
netweft runs a remote MCP server at https://api.netweft.com/mcp. Clients that speak Streamable
HTTP can connect to it directly (see Clients that speak HTTP).
netweft-mcp is for the clients that only start local servers over stdio, such as Claude Desktop
and Windsurf. It relays each message to the remote server with your API key, and relays each
answer back.
Every tool is read-only over data netweft already stores. An agent can read a workspace but cannot change it or spend its credits.
Before you start
- Node.js 20 or later.
npxcomes with it. - An API key. In netweft, open Settings, then API keys, and create one. The key is shown once. Its scopes decide which tools the agent sees.
Install
There is nothing to install by hand. The client runs the package through npx:
npx -y netweft-mcpTo check it works from a terminal:
NETWEFT_API_KEY=nw_... npx -y netweft-mcp --versionClients that start a local server
Claude Desktop
Open Settings, then Developer, then Edit Config, and add netweft to
claude_desktop_config.json:
{
"mcpServers": {
"netweft": {
"command": "npx",
"args": ["-y", "netweft-mcp"],
"env": {
"NETWEFT_API_KEY": "nw_..."
}
}
}
}Restart Claude Desktop. The netweft tools appear under the tools menu.
Windsurf, and any other stdio client
Most clients take the same shape: a command, its arguments, and an environment. In Windsurf that
is ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"netweft": {
"command": "npx",
"args": ["-y", "netweft-mcp"],
"env": {
"NETWEFT_API_KEY": "nw_..."
}
}
}
}Gemini CLI
In ~/.gemini/settings.json, reading the key from your shell:
{
"mcpServers": {
"netweft": {
"command": "npx",
"args": ["-y", "netweft-mcp"],
"env": {
"NETWEFT_API_KEY": "$NETWEFT_API_KEY"
}
}
}
}Clients that speak HTTP
These connect to the remote server directly. netweft-mcp works with them too, but it is one more
process to run.
Claude Code
claude mcp add --transport http netweft https://api.netweft.com/mcp \
--header "Authorization: Bearer $NETWEFT_API_KEY"Or, to share the setup with a project without sharing the key, add it to .mcp.json and keep the
key in your environment:
{
"mcpServers": {
"netweft": {
"type": "http",
"url": "https://api.netweft.com/mcp",
"headers": {
"Authorization": "Bearer ${NETWEFT_API_KEY}"
}
}
}
}Cursor
In ~/.cursor/mcp.json, or .cursor/mcp.json in a project:
{
"mcpServers": {
"netweft": {
"url": "https://api.netweft.com/mcp",
"headers": {
"Authorization": "Bearer ${env:NETWEFT_API_KEY}"
}
}
}
}VS Code
In .vscode/mcp.json. VS Code asks for the key the first time and keeps it out of the file:
{
"inputs": [
{
"type": "promptString",
"id": "netweft-key",
"description": "netweft API key",
"password": true
}
],
"servers": {
"netweft": {
"type": "http",
"url": "https://api.netweft.com/mcp",
"headers": {
"Authorization": "Bearer ${input:netweft-key}"
}
}
}
}Codex CLI
In ~/.codex/config.toml:
[mcp_servers.netweft]
url = "https://api.netweft.com/mcp"
bearer_token_env_var = "NETWEFT_API_KEY"Configuration
| Variable | Required | What it does |
| --- | --- | --- |
| NETWEFT_API_KEY | yes | The API key, nw_<prefix>_<secret>. |
| NETWEFT_API_URL | no | A self-hosted netweft API, such as https://api.example.com. /mcp is added. Defaults to https://api.netweft.com. Must be https, except for localhost: the key travels in a header. |
netweft-mcp --help prints the same.
What an agent can do
Start an agent with list_projects to get project ids; most other tools take one.
| Scope | Tools |
| --- | --- |
| Projects | whoami, list_projects, get_project, get_project_overview |
| Keywords | list_saved_keywords, list_keyword_tags |
| Rank tracking | list_rank_trackers, get_rank_tracker, list_tracked_keywords, get_latest_rank_results, get_rank_position_matrix, get_rank_trend, get_keyword_rank_history, estimate_rank_check_cost |
| Site audit | list_audits, get_audit, list_audit_issues, list_audit_pages |
| Context | get_project_context, list_competitors, list_key_pages, list_research_log, list_backlink_snapshots |
| Billing | get_credit_balance, get_subscription |
The server lists only the tools the key's scopes allow. The full reference is at netweft.com/docs/mcp-server.
Troubleshooting
netweft-mcp writes protocol messages to stdout and everything else to stderr, which most clients
show in their MCP log.
NETWEFT_API_KEY is not set: the client did not pass the key. Put it underenvin the client's config, not in your shell profile, unless the client passes your environment through.netweft answered 401: the key is wrong, revoked or past its expiry. Issue a new one.netweft answered 429: one key can make a limited number of requests a minute. The message says how long to wait.Could not reach netweft: check the network, andNETWEFT_API_URLif you set it.netweft did not answer within 120 seconds: the request was given up on. Try it again.
Protocol
The server speaks MCP 2026-07-28 statelessly and the handshake revisions 2025-11-25,
2025-06-18 and 2025-03-26. netweft-mcp passes either through: it adds the key, mirrors the
headers the transport requires, and remembers the version a handshake settled on. A client's
notifications/cancelled stops the request it names, and a streamed answer is relayed event by
event as it arrives.
License
FSL-1.1-ALv2. The netweft name and logo are not licensed.
