Skip to main content
Neptune works with any AI tool that supports the Model Context Protocol (MCP). This guide covers how to connect using STDIO or HTTP transport.

​
Prerequisites

  • Python 3.13+ installed
  • uv package manager
  • macOS
  • Linux
  • Windows
brew install uv
Most MCP clients use STDIO transport, where the client spawns the MCP server as a subprocess and communicates via stdin/stdout.

​
The Command

uvx --from git+https://github.com/shuttle-hq/neptune-cli-python.git neptune mcp

​
Configuration Format

Most clients use a JSON configuration like this:
  • macOS / Linux
  • Windows
{
  "mcpServers": {
    "neptune": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/shuttle-hq/neptune-cli-python.git", "neptune", "mcp"]
    }
  }
}
On Windows, you need to wrap the command with cmd /c because most MCP clients can’t directly execute uvx.

​
Where to Put This Configuration

ClientConfig Location
CursorSettings → Tools & MCP → Add new MCP server
Claude Desktop (macOS)~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Linux)~/.config/Claude/claude_desktop_config.json
Claude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.json
VS Code + ClineVS Code Settings → search “Cline MCP” → Edit in settings.json
WindsurfSettings → Cascade → MCP Servers
Warp~/.warp/mcp.json

​
Option 2: HTTP Transport

If your client doesn’t support STDIO, or you prefer HTTP, you can run the Neptune MCP as an HTTP server.

​
Start the Server

uvx --from git+https://github.com/shuttle-hq/neptune-cli-python.git neptune mcp --transport=http
The server starts at http://localhost:8001/mcp by default.

​
Connect Your Client

Configure your MCP client to connect to: 
http://localhost:8001/mcp

​
Custom Port

To use a different port: 
uvx --from git+https://github.com/shuttle-hq/neptune-cli-python.git neptune mcp --transport=http --port=9000
The HTTP server must be running before your AI client tries to connect. Consider running it in a separate terminal or as a background service.

​
Available Tools

Once connected, your AI assistant has access to these Neptune tools:
ToolDescription
loginAuthenticate via GitHub OAuth
get_project_schemaGet the neptune.json schema
add_new_resourceGet info about resource types
provision_resourcesCreate cloud infrastructure
deploy_projectBuild and deploy your app
get_deployment_statusCheck deployment status
wait_for_deploymentWait for deployment to complete
get_logsRetrieve application logs
set_secret_valueSet a secret’s value
list_bucket_filesList files in a storage bucket
get_bucket_objectRetrieve an object from a bucket
delete_projectDelete project and resources

​
Troubleshooting

Make sure uv is installed and in your PATH:
uv --version
If not found, reinstall uv and restart your terminal/shell.
Neptune MCP requires Python 3.13+. Check your version:
python --version
If needed, install Python 3.13+ from python.org.
Try running the command manually in your terminal to see error messages:
uvx --from git+https://github.com/shuttle-hq/neptune-cli-python.git neptune mcp
Press Ctrl+C to stop.
  1. Make sure the HTTP server is running before connecting
  2. Check if something else is using port 8001
  3. Try a different port with --port=9000
On Windows, always wrap with cmd /c:
{
  "command": "cmd",
  "args": ["/c", "uvx", "--from", "..."]
}

​
Next Steps

Once connected, head to the Quickstart to authenticate and deploy your first app.