{"id":"a926befe-d319-417f-ab8f-7c38d043833f","slug":"nearweek-mcp","kind":"mcp","name":"MCP","summary":"MCP server for the NEAR Ecosystem","owner":"NEARWEEK","repoUrl":"https://github.com/NEARWEEK/MCP","license":"MPL-2.0","licenseTier":"weak-copyleft","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-10-02T09:20:08.000Z","addedAt":"2026-10-21T16:01:09.368Z","logoUrl":"https://avatars.githubusercontent.com/u/91823765?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-24T11:47:04.520Z","sample":false,"url":"https://conduits.dev/tools/nearweek-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"@nearweek/mcp-server"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# NEARWEEK MCP Server\n\nModel Context Protocol (MCP) server for accessing NEAR blockchain data. Provides tools and resources for querying accounts, blocks, contracts, and transactions on NEAR Protocol.\n\n## Related Repositories\n\n- **[MCP Backend API](https://github.com/NEARWEEK/mcp-backend-api)** - Authentication backend service for API key management\n\n## Features\n\n### Tools\n\n- **Block Operations**\n  - `near.getBlock` - Get block details by hash, height, or finality\n  - `near.getBlockChanges` - Get all state changes in a block\n  - `near.getChunk` - Get chunk details\n\n- **Account Operations**\n  - `near.getAccount` - View account details (balance, storage, etc.)\n  - `near.getAccountChanges` - View account state changes\n  - `near.getAccessKeys` - List all access keys for an account\n  - `near.getAccessKey` - View specific access key details\n\n- **Contract & Transaction Operations**\n  - `near.viewFunction` - Call read-only contract view methods\n  - `near.getTransaction` - Get transaction status with receipts\n  - `near.rpc` - Make generic NEAR RPC calls\n\n### Resources\n\n**Static Resources:**\n- `near://blocks/latest?count=N` - Recent blocks feed\n- `near://network/status` - Network status and protocol info\n\n**Resource Templates (parameterized):**\n- `near://account/{account_id}` - Account summary card\n- `near://contract/{account_id}/readme` - Contract info and suggested methods\n\n## Installation\n\n```bash\nnpm install\nnpm run build\n```\n\n## Usage\n\n### Running the Server\n\nThe server supports two transport modes: **stdio** (default) and **HTTP**.\n\n#### Stdio Mode (for MCP clients like Claude Desktop)\n\n```bash\n# Mainnet (default)\nnpm start\n\n# Testnet\nNEAR_NETWORK=testnet npm start\n# or\nnpm start testnet\n```\n\n#### HTTP Mode (for web-based clients)\n\n```bash\n# Mainnet on port 3000 (default)\nnpm start -- --http\n\n# Testnet on custom port\nnpm start testnet --http --port=8080\n\n# Using npm scripts\nnpm run start:http\nnpm run start:streamableHttp  # Explicit alias for Streamable HTTP transport\n\n# With environment variables\nPORT=8080 NEAR_NETWORK=testnet npm start -- --http\n```\n\nThe HTTP server provides:\n- **MCP endpoint**: `http://localhost:3000/mcp` (GET/POST/DELETE) - Streamable HTTP transport with session management (requires authentication)\n- **RPC endpoint**: `http://localhost:3000/rpc` (POST) - Simple JSON-RPC for direct requests (requires authentication)\n- **Health check**: `http://localhost:3000/health` (GET) - No authentication required\n\n## Authentication\n\nThe MCP server requires API key authentication for all operations (both stdio and HTTP modes). Authentication is managed by the MCP Backend API service.\n\n### Prerequisites\n\n1. **Start the MCP Backend API**:\n```bash\ncd ../mcp-backend-api\nnpm install\nnpm run build\nnpm start\n```\n\nThe MCP Backend API runs on port 3001 by default. See `../mcp-backend-api/README.md` for details.\n\n2. **Generate an API Key**:\n```bash\ncd ../mcp-backend-api\nnpm run generate:key -- --name=\"My MCP Client\"\n```\n\nSave the generated API key securely - it will be needed for both stdio and HTTP modes.\n\n### Stdio Mode Authentication\n\nAPI key must be provided via the `MCP_API_KEY` or `API_KEY` environment variable:\n\n```bash\n# Set the API key\nexport MCP_API_KEY=your-generated-api-key-here\n\n# Optional: Set MCP Backend API URL (default: http://localhost:3001)\nexport AUTH_BACKEND_URL=http://localhost:3001\n\n# Start the server\nnpm start\n```\n\nThe server will validate the API key on startup and exit if invalid.\n\n### HTTP Mode Authentication\n\nAPI key can be provided in two ways:\n\n**Option 1: Authorization Header (Recommended)**\n\n```bash\n# Start the server\nnpm start -- --http\n\n# Make authenticated requests with Authorization header\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Authorization: Bearer your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n```\n\n**Option 2: Query Parameter**\n\n```bash\n# Make authenticated requests with query parameter\ncurl -X POST \"http://localhost:3000/mcp?apiKey=your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n```\n\n⚠️ **Security Note**: Query parameters appear in server logs and browser history. The Authorization header is more secure for production use.\n\nBoth `/mcp` and `/rpc` endpoints support both authentication methods.\n\n### Configuration\n\nConfigure the server via environment variables or CLI arguments:\n\n#### MCP Server Configuration\n\n- **Network**: `NEAR_NETWORK=mainnet|testnet` or CLI arg `testnet`\n- **Transport**: CLI flag `--http` or `-h` for HTTP mode (default: stdio)\n- **Port**: `PORT=3000` or CLI arg `--port=8080` (HTTP mode only)\n- **RPC URL**: `NEAR_RPC_URL` or `RPC_URL` (overrides default network endpoint)\n- **NEAR API Key**: `NEAR_API_KEY` (for authenticated NEAR RPC providers like FastNEAR)\n\n#### Authentication Configuration\n\n- **MCP API Key**: `MCP_API_KEY` or `API_KEY` (required for stdio mode authentication)\n- **MCP Backend API URL**: `AUTH_BACKEND_URL` (default: `http://localhost:3001`)\n\n#### Logging Configuration\n\nThe MCP server uses a **two-tier logging approach** (HTTP mode only):\n\n1. **Access Logs** - HTTP request/response logging via [morgan](https://github.com/expressjs/morgan)\n2. **Structured Logs** - Application logging via [Pino](https://getpino.io/)\n\n**Configuration:**\n- **Log Level**: `LOG_LEVEL` - Set minimum log level for structured logs (default: `info`)\n- **Access Log Format**: `ACCESS_LOG_FORMAT` - Set format for HTTP access logs\n- **Node Environment**: `NODE_ENV` - Set to `production` for JSON logs, otherwise pretty-printed\n\n##### Access Logs (morgan)\n\nHTTP access logs are **always enabled** in HTTP mode and written to stdout, independent of the `LOG_LEVEL` setting. These provide one-line summaries of each HTTP request.\n\n**Configuration:**\n- Set format via `ACCESS_LOG_FORMAT` environment variable\n- Default: `[:date[iso]] :method :url :status :response-time ms - :res[content-length]`\n\n**Common format tokens:**\n- `:date[iso]` - ISO 8601 timestamp\n- `:method` - HTTP method (GET, POST, etc.)\n- `:url` - Request URL\n- `:status` - HTTP status code\n- `:response-time` - Response time in milliseconds\n- `:res[content-length]` - Response size in bytes\n- `:remote-addr` - Client IP address\n\n**Example access log output:**\n```\n[2025-01-09T14:30:15.123Z] POST /rpc 200 12.456 ms - 345\n[2025-01-09T14:30:20.789Z] GET /health 200 1.234 ms - 78\n[2025-01-09T14:30:25.456Z] POST /mcp 403 5.678 ms - 62\n```\n\nFor more format tokens, see [morgan documentation](https://github.com/expressjs/morgan#tokens).\n\n##### Structured Logs (Pino)\n\nApplication logs for startup messages, errors, and debug information. Controlled by `LOG_LEVEL` environment variable.\n\n**Log Levels:**\n- `fatal` (60) - Fatal errors that cause application termination (includes stack traces)\n- `error` (50) - Error conditions (includes stack traces for 5xx errors)\n- `warn` (40) - Warning conditions\n- `info` (30) - Informational messages (default)\n- `debug` (20) - Debug messages\n- `trace` (10) - Trace messages (very verbose, includes HTTP req/res details)\n\n**Example:**\n```bash\n# Show only warnings and errors\nLOG_LEVEL=warn npm start\n\n# Debug mode for development\nLOG_LEVEL=debug npm start\n\n# Trace level (includes detailed HTTP request logging)\nLOG_LEVEL=trace npm start\n\n# Production mode with JSON logs\nNODE_ENV=production npm start\n```\n\n**HTTP Request Logging Behavior:**\n- **Normal requests (2xx, 3xx)**: Only logged to access log\n- **Client errors (4xx)**: Only logged to access log\n- **Server errors (5xx)**: Logged to access log + error level in structured log\n- **Trace level**: All requests logged to structured log with req/res details\n\n**Development mode** (NODE_ENV != production):\n```\n[14:30:15.123] INFO: NEARWEEK MCP Server running on mainnet (HTTP mode)\n[14:30:30.123] ERROR: POST /rpc 500\n[14:30:35.456] TRACE: POST /health 200\n    method: \"POST\"\n    url: \"/health\"\n    statusCode: 200\n    responseTime: 12\n```\n\n**Production mode** (NODE_ENV=production):\n```json\n{\"level\":30,\"time\":1673270415123,\"msg\":\"NEARWEEK MCP Server running on mainnet (HTTP mode)\"}\n{\"level\":50,\"time\":1673270430123,\"msg\":\"POST /rpc 500\"}\n{\"level\":10,\"time\":1673270435456,\"method\":\"POST\",\"url\":\"/health\",\"statusCode\":200,\"responseTime\":12,\"msg\":\"POST /health 200\"}\n```\n\n**Log Separation:**\n- **Access logs**: All HTTP requests (always on in HTTP mode)\n- **Structured logs**: Application messages, errors, and (at trace level) HTTP details\n- At `trace` level: Both access logs and structured logs include HTTP request details\n\n**Note**: Stdio mode only has structured logs (no HTTP access logs), and they're written to stderr to avoid interfering with the MCP protocol on stdout.\n\n#### Using Custom RPC Providers\n\nTo use alternative RPC providers like FastNEAR with API key authentication:\n\n```bash\n# With API key\nNEAR_RPC_URL=\"https://rpc.mainnet.fastnear.com\" \\\nNEAR_API_KEY=\"your-api-key-here\" \\\nnpm start\n\n# Custom RPC without API key\nNEAR_RPC_URL=\"https://your-custom-rpc.com\" npm start\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Watch mode\nnpm run dev\n\n# Type checking\nnpm run typecheck\n```\n\n## MCP Client Configuration\n\n### Stdio Transport (Claude Desktop, VS Code, etc.)\n\nAdd to your MCP client configuration with your API key:\n\n```json\n{\n  \"mcpServers\": {\n    \"near\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/nearweek/src/MCP/dist/index.js\", \"mainnet\"],\n      \"env\": {\n        \"NEAR_NETWORK\": \"mainnet\",\n        \"MCP_API_KEY\": \"your-generated-api-key-here\",\n        \"AUTH_BACKEND_URL\": \"http://localhost:3001\"\n      }\n    }\n  }\n}\n```\n\n**Important**: Replace `your-generated-api-key-here` with an actual API key generated using the MCP Backend API's CLI tool.\n\n### HTTP Transport (Web-based clients)\n\nStart the server in HTTP mode and connect to:\n- Base URL: `http://localhost:3000`\n- **MCP Endpoint**: `http://localhost:3000/mcp` - Full MCP protocol with Streamable HTTP transport\n  - Supports GET (SSE streams), POST (JSON-RPC messages), DELETE (session termination)\n  - Includes session management with `Mcp-Session-Id` headers\n  - Complies with MCP specification 2025-03-26\n- **RPC Endpoint**: `http://localhost:3000/rpc` - Simple JSON-RPC endpoint for non-MCP clients\n\n#### Using the MCP endpoint (for MCP clients)\n\nMCP clients should use the `/mcp` endpoint with proper protocol headers. The server manages sessions automatically.\n\n**With Authorization Header:**\n\n```bash\n# Example authenticated MCP request\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Authorization: Bearer your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"params\":{},\"id\":1}'\n```\n\n**With Query Parameter:**\n\n```bash\n# Example using query parameter\ncurl -X POST \"http://localhost:3000/mcp?apiKey=your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"params\":{},\"id\":1}'\n```\n\n#### Using the RPC endpoint (for simple HTTP clients)\n\nFor direct JSON-RPC requests without MCP protocol overhead (still requires authentication):\n\n**With Authorization Header:**\n\n```bash\n# List available tools\ncurl -X POST http://localhost:3000/rpc \\\n  -H \"Authorization: Bearer your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1}'\n\n# Call a tool\ncurl -X POST http://localhost:3000/rpc \\\n  -H \"Authorization: Bearer your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"near.getBlock\",\n      \"arguments\": {\"finality\": \"final\"}\n    },\n    \"id\": 2\n  }'\n```\n\n**With Query Parameter:**\n\n```bash\n# List available tools\ncurl -X POST \"http://localhost:3000/rpc?apiKey=your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1}'\n\n# Call a tool\ncurl -X POST \"http://localhost:3000/rpc?apiKey=your-generated-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"near.getBlock\",\n      \"arguments\": {\"finality\": \"final\"}\n    },\n    \"id\": 2\n  }'\n```\n\n## Public Server\n\nA public instance of this MCP server is available at **https://mcp.nearweek.com/mcp** for immediate use without local installation.\n\n### Connecting Popular MCP Clients\n\nTo use the public server, you'll need an API key. Contact the service administrator or visit the authentication backend to obtain one.\n\n#### Claude Code\n\nAdd the server using the Claude Code CLI:\n\n**Option 1: Using Authorization Header (Recommended)**\n```bash\nclaude mcp add --transport http nearweek https://mcp.nearweek.com/mcp \\\n  --header \"Authorization: Bearer Your_API_key\"\n```\n\n**Option 2: Using Query Parameter**\n```bash\nclaude mcp add --transport http nearweek \"https://mcp.nearweek.com/mcp?apiKey=Your_API_key\"\n```\n\n⚠️ **Security Note**: Replace `Your_API_key` with your actual API key. The Authorization header method is more secure for production use.\n\n#### Visual Studio Code\n\nAdd to your VS Code MCP settings (`.vscode/mcp.json` or user settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"nearweek\": {\n      \"transport\": \"http\",\n      \"url\": \"https://mcp.nearweek.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer Your_API_key\"\n      }\n    }\n  }\n}\n```\n\n#### MCP Inspector\n\n1. Start the inspector:\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\n2. In your browser, configure the connection on the left side:\n   - **Transport Type**: `Streamable HTTP`\n   - **URL**: `https://mcp.nearweek.com/mcp`\n\n3. Open the **Authentication** dialog, switch to **JSON mode**, and paste in the **Custom Headers (JSON)** field:\n```json\n{\n  \"Authorization\": \"Bearer Your_API_key\"\n}\n```\n\n## Requirements\n\n- Node.js 22 or higher\n- TypeScript 5.7+\n\n## Architecture\n\n- **Runtime**: Node.js 22+ with ES2022 modules\n- **Transport**:\n  - MCP stdio transport for desktop clients\n  - Streamable HTTP transport (MCP 2025-03-26 spec) for web clients\n  - Session management with cryptographically secure UUIDs\n- **NEAR SDK**: near-api-js v5+ official JavaScript SDK\n- **RPC**: NEAR JSON RPC via JsonRpcProvider with optional API key authentication\n- **Validation**: Zod schemas for all inputs\n- **HTTP Server**: Express.js with dual endpoints:\n  - `/mcp` - Full MCP protocol with Streamable HTTP transport\n  - `/rpc` - Simple JSON-RPC for non-MCP clients\n\n## License\n\nThis project is licensed under the [Mozilla Public License Version 2.0](LICENSE).\n\n[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)\n"}