|
| 1 | +# Cursor Integration |
| 2 | + |
| 3 | +This guide explains how to configure Cursor IDE for use with the Mapbox MCP DevKit Server. |
| 4 | + |
| 5 | +## Requirements |
| 6 | + |
| 7 | +- [Cursor](https://www.cursor.com/) installed |
| 8 | +- Mapbox MCP DevKit Server [built locally](../README.md#development-setup) |
| 9 | + |
| 10 | +```sh |
| 11 | +# from repository root: |
| 12 | +# using node |
| 13 | +npm run build |
| 14 | + |
| 15 | +# note your absolute path to node, you will need it for MCP config |
| 16 | +# For Mac/Linux |
| 17 | +which node |
| 18 | +# For Windows |
| 19 | +where node |
| 20 | + |
| 21 | +# or alternatively, using docker |
| 22 | +docker build -t mapbox-mcp-devkit . |
| 23 | +``` |
| 24 | + |
| 25 | +## Setup Instructions |
| 26 | + |
| 27 | +### Configure Cursor to use Mapbox MCP DevKit Server |
| 28 | + |
| 29 | +1. Go to Cursor Settings/ MCP Tools and click on "Add Custom MCP". |
| 30 | +2. Add either of the following MCP config: |
| 31 | + - **NPM version** (recommended for simplicity) |
| 32 | + |
| 33 | + ```json |
| 34 | + { |
| 35 | + "mcpServers": { |
| 36 | + "MapboxDevKit": { |
| 37 | + "type": "stdio", |
| 38 | + "command": "<PATH_TO_YOUR_NPX>", |
| 39 | + "args": ["-y", "@mapbox/mcp-devkit-server"], |
| 40 | + "env": { |
| 41 | + "MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>", |
| 42 | + "MCP_LOGGING_DISABLE": "true" |
| 43 | + } |
| 44 | + } |
| 45 | + } |
| 46 | + } |
| 47 | + ``` |
| 48 | + |
| 49 | + - **Docker version** (recommended for isolation) |
| 50 | + |
| 51 | + ```json |
| 52 | + { |
| 53 | + "mcpServers": { |
| 54 | + "MapboxDevKit": { |
| 55 | + "type": "stdio", |
| 56 | + "command": "docker", |
| 57 | + "args": [ |
| 58 | + "run", |
| 59 | + "-i", |
| 60 | + "--rm", |
| 61 | + "--env", |
| 62 | + "MAPBOX_ACCESS_TOKEN=<YOUR_TOKEN>", |
| 63 | + "--env", |
| 64 | + "MCP_LOGGING_DISABLE=true", |
| 65 | + "mapbox-mcp-devkit" |
| 66 | + ] |
| 67 | + } |
| 68 | + } |
| 69 | + } |
| 70 | + ``` |
| 71 | + |
| 72 | + - **Node version** (for local development) |
| 73 | + ```json |
| 74 | + { |
| 75 | + "mcpServers": { |
| 76 | + "MapboxDevKit": { |
| 77 | + "type": "stdio", |
| 78 | + "command": "<PATH_TO_YOUR_NODE>", |
| 79 | + "args": ["/YOUR_PATH_TO_GIT_REPOSITORY/dist/esm/index.js"], |
| 80 | + "env": { |
| 81 | + "MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>", |
| 82 | + "MCP_LOGGING_DISABLE": "true" |
| 83 | + } |
| 84 | + } |
| 85 | + } |
| 86 | + } |
| 87 | + ``` |
| 88 | + |
| 89 | +3. Click "Save" to apply the configuration. |
| 90 | + |
| 91 | +## Important Notes |
| 92 | + |
| 93 | +### Stdio Transport Logging |
| 94 | + |
| 95 | +The MCP DevKit Server uses stdio (standard input/output) for communication with Cursor. To prevent console logs from corrupting the JSON-RPC protocol, **you must set `MCP_LOGGING_DISABLE=true`** in the environment variables. |
| 96 | + |
| 97 | +Both variable names are supported for backwards compatibility: |
| 98 | + |
| 99 | +- `MCP_LOGGING_DISABLE` (recommended) |
| 100 | +- `MCP_DISABLE_LOGGING` (legacy) |
| 101 | + |
| 102 | +### Token Scopes |
| 103 | + |
| 104 | +Your Mapbox access token must have the appropriate scopes for the tools you want to use. See the [main README](../README.md#tools) for required token scopes per tool. |
| 105 | + |
| 106 | +### Configuration Options |
| 107 | + |
| 108 | +Additional environment variables you can set: |
| 109 | + |
| 110 | +- `OTEL_EXPORTER_OTLP_ENDPOINT` - Enable OpenTelemetry tracing (see [tracing docs](./tracing.md)) |
| 111 | +- `OTEL_SERVICE_NAME` - Override service name for tracing |
| 112 | +- `MAPBOX_API_ENDPOINT` - Override Mapbox API endpoint (advanced) |
| 113 | + |
| 114 | +## Troubleshooting |
| 115 | + |
| 116 | +### Server Not Appearing |
| 117 | + |
| 118 | +If the Mapbox DevKit Server doesn't appear in Cursor's MCP tools: |
| 119 | + |
| 120 | +1. Check that your `MAPBOX_ACCESS_TOKEN` is valid |
| 121 | +2. Verify the path to `node` or `npx` is correct |
| 122 | +3. For Docker: ensure the image is built with `docker images | grep mapbox-mcp-devkit` |
| 123 | +4. Check Cursor's logs for any error messages |
| 124 | + |
| 125 | +### Connection Errors |
| 126 | + |
| 127 | +If you see JSON-RPC or parsing errors: |
| 128 | + |
| 129 | +1. Ensure `MCP_LOGGING_DISABLE` is set to `"true"` in your configuration |
| 130 | +2. If using Node version, verify the path to `dist/esm/index.js` is correct |
| 131 | +3. Run `npm run build` to ensure the latest build is available |
| 132 | + |
| 133 | +### Tool Execution Failures |
| 134 | + |
| 135 | +If tools fail to execute: |
| 136 | + |
| 137 | +1. Verify your Mapbox token has the required scopes (see [README](../README.md)) |
| 138 | +2. Check if you're hitting rate limits (429 errors) |
| 139 | +3. Enable verbose errors by adding `"VERBOSE_ERRORS": "true"` to the env config |
| 140 | + |
| 141 | +## Example Usage |
| 142 | + |
| 143 | +Once configured, you can use natural language to interact with Mapbox tools: |
| 144 | + |
| 145 | +- "List all my Mapbox styles" |
| 146 | +- "Show me the bounding box for San Francisco" |
| 147 | +- "Convert these coordinates to lat/lng: -122.4194, 37.7749" |
| 148 | +- "Create a new Mapbox style called 'my-custom-map'" |
| 149 | + |
| 150 | +See the [README](../README.md#example-prompts) for more example prompts. |
0 commit comments