{"id":49443246,"url":"https://github.com/lirantal/automcp","last_synced_at":"2026-04-29T21:06:31.477Z","repository":{"id":322830472,"uuid":"1089027824","full_name":"lirantal/automcp","owner":"lirantal","description":"AutoMCP scaffolds your Model Context Protocol config from package.json deps","archived":false,"fork":false,"pushed_at":"2026-04-27T19:49:28.000Z","size":5911,"stargazers_count":5,"open_issues_count":14,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T21:25:46.379Z","etag":null,"topics":["agentic-ai","agents","ai","artificial-intelligence","claude-code","cursor-ai","github-copilot","mcp","model-context-protocol","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"https://lirantal.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lirantal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-03T19:34:47.000Z","updated_at":"2026-04-26T08:47:09.000Z","dependencies_parsed_at":"2025-12-08T18:03:51.863Z","dependency_job_id":null,"html_url":"https://github.com/lirantal/automcp","commit_stats":null,"previous_names":["lirantal/automcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lirantal/automcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fautomcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fautomcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fautomcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fautomcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lirantal","download_url":"https://codeload.github.com/lirantal/automcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fautomcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32443618,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T20:22:27.477Z","status":"ssl_error","status_checked_at":"2026-04-29T20:22:26.507Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agents","ai","artificial-intelligence","claude-code","cursor-ai","github-copilot","mcp","model-context-protocol","modelcontextprotocol"],"created_at":"2026-04-29T21:06:30.222Z","updated_at":"2026-04-29T21:06:31.470Z","avatar_url":"https://github.com/lirantal.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable --\u003e\n\n\u003cp align=\"center\"\u003e\u003ch1 align=\"center\"\u003e\n  automcp\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  AutoMCP detects your package manifest file and automatically adds relevant MCP (Model Context Protocol) servers to the coding agents it detects\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.org/package/automcp\"\u003e\u003cimg src=\"https://badgen.net/npm/v/automcp\" alt=\"npm version\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.org/package/automcp\"\u003e\u003cimg src=\"https://badgen.net/npm/license/automcp\" alt=\"license\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.org/package/automcp\"\u003e\u003cimg src=\"https://badgen.net/npm/dt/automcp\" alt=\"downloads\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lirantal/automcp/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/lirantal/automcp/actions/workflows/ci.yml/badge.svg?branch=main\" alt=\"build\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/lirantal/automcp\"\u003e\u003cimg src=\"https://badgen.net/codecov/c/github/lirantal/automcp?type=h\" alt=\"codecov\"/\u003e\u003c/a\u003e\n  \u003ca href=\"./SECURITY.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg?type=h\" alt=\"Responsible Disclosure Policy\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n![AutoMCP screenshot](./.github/automcp-screenshot.png)\n\n\n## Features\n\n- 🔍 **Auto-detects** your coding agent (Cursor, VS Code, Claude Desktop)\n- 📦 **Scans** your project dependencies from package.json\n- 🔗 **Resolves** each package to its GitHub repository\n- 🌐 **Generates** GitMCP server URLs automatically\n- ✅ **Never overwrites** existing MCP server configurations\n- 🚫 **Prevents duplicates** via smart URL normalization\n- 🏃 **Fast** concurrent resolution with connection pooling\n- 🧪 **Dry-run mode** to preview changes safely\n- 🎯 **Zero runtime dependencies** — uses only Node.js built-ins\n\n## Install\n\nYou can run `automcp` with npx (no install required) or add it to your project.\n\n```sh\nnpx automcp\n# or\nnpm add -D automcp\n```\n\n## Usage: CLI\n\n\u003chttps://github.com/user-attachments/assets/305f75f8-0fec-4dd2-886c-d5f23a5e8a7e\u003e\n\n```sh\nnpx automcp [options]\n```\n\n### Options\n\n- `--dry-run`: Show planned changes without writing\n- `--agent \u003cname\u003e`: Override detected agent (e.g., cursor, vscode)\n- `--config \u003cpath\u003e`: Override MCP config file path\n- `--include-dev`: Include devDependencies (default: false)\n- `--silent`: Minimal output\n- `--json`: JSON summary output\n- `-h`, `--help`: Show help\n- `-v`, `--version`: Show version\n\n### Examples\n\n```sh\n# Preview changes only\nnpx automcp --dry-run\n\n# Explicitly target Cursor and a custom config path\nnpx automcp --agent cursor --config ~/.cursor/mcp.json\n\n# Include devDependencies\nnpx automcp --include-dev\n\n# JSON output for CI/automation\nnpx automcp --json\n```\n\n### Understanding `--agent` and `--config` Flags\n\nThe `--agent` and `--config` flags are **flexible and work independently or together**. You don't need to provide both!\n\n#### Usage Patterns\n\n| Command | Agent Detection | Config Path | When to Use |\n|---------|----------------|-------------|-------------|\n| `npx automcp` | Auto-detected from `.cursor/` or `.vscode/` | Auto-detected | ✅ **Recommended:** Let AutoMCP detect everything |\n| `npx automcp --agent cursor` | Use \"cursor\" | Auto-resolves to `.cursor/mcp.json` | When you have multiple agents and want to target one |\n| `npx automcp --config /path/to/mcp.json` | Inferred from path | Use specified path | When config is in a custom location |\n| `npx automcp --agent cursor --config /custom/path.json` | Use \"cursor\" | Use specified path | Full manual control |\n\n#### How Each Flag Works\n\n**Using `--agent` alone:**\n- Resolves the config path automatically based on the agent name\n- `cursor` → `.cursor/mcp.json` in your project\n- `vscode` → `.vscode/mcp.json` in your project\n- Creates the file if it doesn't exist\n\n**Using `--config` alone:**\n- Infers the agent name from the path\n- Path contains \"cursor\" → agent = \"cursor\"\n- Path contains \"vscode\" → agent = \"vscode\"\n- Path contains \"claude\" → agent = \"claude-desktop\"\n- Otherwise → agent = \"unknown\"\n\n**Using both together:**\n- Explicitly sets both values with no auto-detection\n- Useful for custom setups or non-standard paths\n\n#### Examples\n\n```sh\n# Let AutoMCP detect both (most common)\nnpx automcp\n\n# Target Cursor specifically, auto-resolve config path\nnpx automcp --agent cursor\n\n# Use a custom config path, agent inferred as \"cursor\"\nnpx automcp --config ~/.cursor/mcp.json\n\n# Use a custom config path, agent inferred as \"unknown\"\nnpx automcp --config /tmp/my-mcp-config.json\n\n# Explicitly set both for full control\nnpx automcp --agent cursor --config /custom/location/mcp.json\n```\n\n### How It Works\n\n1. **Detects your coding agent** (Cursor, VS Code) and locates its **local project** MCP config file\n2. **Reads your package.json** dependencies\n3. **Resolves each dependency** to its GitHub repository via `npm view`\n4. **Builds GitMCP URLs** in the format `https://gitmcp.io/owner/repo`\n5. **Updates your MCP config** without overwriting existing entries or creating duplicates\n\n\u003e **Note:** AutoMCP only updates local project configurations (e.g., `.cursor/mcp.json` or `.vscode/mcp.json` in your project directory). It does not modify global agent configurations in your home directory.\n\n## Quick Start\n\n```sh\n# Run in your project directory\ncd my-project\nnpx automcp\n\n# Preview changes first\nnpx automcp --dry-run\n\n# Include devDependencies\nnpx automcp --include-dev\n```\n\n### Real-World Example\n\nGiven a project with these dependencies:\n\n```json\n{\n  \"dependencies\": {\n    \"express\": \"^4.18.0\",\n    \"lodash\": \"^4.17.21\",\n    \"axios\": \"^1.6.0\"\n  }\n}\n```\n\nRunning `npx automcp` will:\n\n1. Detect your agent (e.g., Cursor at `.cursor/mcp.json` in your project)\n2. Resolve GitHub repos:\n   - express → expressjs/express\n   - lodash → lodash/lodash\n   - axios → axios/axios\n3. Add to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"express Docs\": {\n      \"url\": \"https://gitmcp.io/expressjs/express\"\n    },\n    \"lodash Docs\": {\n      \"url\": \"https://gitmcp.io/lodash/lodash\"\n    },\n    \"axios Docs\": {\n      \"url\": \"https://gitmcp.io/axios/axios\"\n    }\n  }\n}\n```\n\n### Supported Agents\n\nAutoMCP looks for agent configurations in the following locations:\n\n- **Cursor** — `.cursor/mcp.json` (in your project directory)\n- **VS Code** — `.vscode/mcp.json` (in your project directory)\n\nUse `--agent` and `--config` flags to override auto-detection or to specify a custom config location.\n\n\u003e **Important:** AutoMCP only updates local project configurations. If no local agent configuration is found (e.g., no `.cursor/` or `.vscode/` directory in your project), the tool will exit without making changes. This prevents accidental updates to global configurations.\n\n### Troubleshooting\n\n**Agent not detected**\n```sh\nnpx automcp --agent cursor --config ~/.cursor/mcp.json\n```\n\n**Permission errors**\nEnsure you have write access to the MCP config directory.\n\n**Non-GitHub packages skipped**\nOnly packages with GitHub repositories are supported. Packages without a `repository` field or with non-GitHub URLs will be skipped.\n\n**URL resolution timeouts**\nThe CLI runs `npm view` with a 10-second timeout per package. Slow network or large dependency lists may take time.\n\n### Output Example\n\n**Standard output:**\n```\n🔍 Agent: cursor\n📝 Config: /Users/username/.cursor/mcp.json\n\n✅ Added 3 MCP servers:\n\n   • express Docs\n     https://gitmcp.io/expressjs/express\n\n   • lodash Docs\n     https://gitmcp.io/lodash/lodash\n\n   • axios Docs\n     https://gitmcp.io/axios/axios\n\n✨ MCP config updated successfully!\n```\n\n**With dry-run:**\n```\n🔍 Agent: cursor\n📝 Config: /Users/username/.cursor/mcp.json\n🧪 Dry-run mode: no files will be modified\n\n✅ Added 5 MCP servers:\n\n   • express Docs\n     https://gitmcp.io/expressjs/express\n\n   • lodash Docs\n     https://gitmcp.io/lodash/lodash\n\n💡 Run without --dry-run to apply these changes.\n```\n\n**With duplicates:**\n```\n🔍 Agent: cursor\n📝 Config: /Users/username/.cursor/mcp.json\n\n⏭️  Skipped 2 duplicates:\n\n   • express Docs\n     https://gitmcp.io/expressjs/express\n\n   • lodash Docs\n     https://gitmcp.io/lodash/lodash\n```\n\n**JSON output (for CI/automation):**\n```sh\nnpx automcp --json\n```\n```json\n{\n  \"ok\": true,\n  \"result\": {\n    \"added\": 3,\n    \"skipped\": 0,\n    \"errors\": 0,\n    \"addedServers\": [\n      {\n        \"name\": \"express Docs\",\n        \"url\": \"https://gitmcp.io/expressjs/express\"\n      }\n    ],\n    \"skippedServers\": [],\n    \"configPath\": \"/Users/username/.cursor/mcp.json\",\n    \"agentName\": \"cursor\",\n    \"dryRun\": false\n  }\n}\n```\n\n## Node.js Compatibility\n\n- **Requires:** Node.js \u003e= 22.0.0\n- Uses ES2022+ features and Node.js built-in APIs\n- No external runtime dependencies\n\n## CI/CD Integration\n\nUse `--json` and `--silent` flags for automation:\n\n```yaml\n# GitHub Actions example\n- name: Update MCP config\n  run: |\n    npx automcp --json --silent \u003e result.json\n    cat result.json\n```\n\nExit codes:\n- `0`: Success (including when nothing to add)\n- `1`: Fatal error (config parse failure, permission denied, missing package.json)\n\n## Contributing\n\nPlease consult [CONTRIBUTING](./.github/CONTRIBUTING.md) for guidelines on contributing to this project.\n\n## Author\n\n**automcp** © [Liran Tal](https://github.com/lirantal), Released under the [Apache-2.0](./LICENSE) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flirantal%2Fautomcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flirantal%2Fautomcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flirantal%2Fautomcp/lists"}