MCP Comprehensive Guide (Ultimate Edition)

---

What is MCP?

The Model Context Protocol (MCP) is a framework to connect tools, APIs, and data sources into a unified, programmable environment. This guide helps you clone, install, configure, and troubleshoot the entire MCP ecosystem, including Git and GitHub MCP servers.

---

Table of Contents

1. Prerequisites
2. Cloning Repositories
3. Installing Dependencies
4. Building MCP Servers
5. Configuring Authentication
6. Registering MCP Servers
7. Running & Testing
8. Troubleshooting
9. Common Errors & Fixes (Detailed)
10. Additional Tips
11. Resources
12. Contributing

---

1. Prerequisites

• Node.js (v14+) → Download
• Python (3.7+) → Download
• Git → Download
• GitHub Account with a Personal Access Token (PAT) → Generate Token
  • Scopes: repo, workflow, read:org

Verify installations:

node -v
npm -v
python --version
git --version

Optional: Create a Python virtual environment:

python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # macOS/Linux

---

2. Cloning Repositories

Clone this guide and all related MCP servers:

git clone https://github.com/VoiceLessQ/mcp-comprehensive-guide.git
git clone https://github.com/VoiceLessQ/github-mcp.git
git clone https://github.com/VoiceLessQ/git-mcp.git
# Clone other MCP servers as needed

Verify:

ls mcp-comprehensive-guide
ls github-mcp
ls git-mcp

Common Errors & Fixes

Error	Cause	Fix
fatal: repository not found	Wrong URL or permissions	Check URL, login to GitHub
Permission denied	SSH key issues	Use HTTPS or fix SSH keys

---

3. Installing Dependencies

Node.js Servers (e.g., GitHub MCP)

cd github-mcp
npm install
npm run build

Python Servers (e.g., Git MCP)

cd git-mcp
pip install -r requirements.txt

Common Errors & Fixes

Error	Cause	Fix
Module not found	Missing deps	Run npm install or pip install
Build failed	TypeScript errors	Fix errors, then npm run build

---

4. Building MCP Servers

• For TypeScript servers, always run:

npm run build

• Verify build output exists (dist/ or build/ directory).

Common Errors & Fixes

Error	Cause	Fix
Cannot find module	Wrong build path	Check MCP config paths
Syntax errors	TypeScript issues	Fix code, rebuild

---

5. Configuring Authentication

Generate GitHub Token

• Go to GitHub Tokens
• Click Generate new token
• Select scopes: repo, workflow, read:org
• Copy and save the token securely

Update MCP Settings

Edit cline_mcp_settings.json (usually in VSCode global storage):

{
  "github": {
    "command": "node",
    "args": ["C:/path/to/github-mcp/dist/index.js"],
    "env": {
      "GITHUB_TOKEN": "your-token-here"
    }
  },
  "git": {
    "command": "python",
    "args": ["-m", "mcp_server_git", "--repository", "C:/path/to/git-mcp/test-repo"]
  }
}

• Use absolute paths.
• Validate JSON syntax.

Common Errors & Fixes

Error	Cause	Fix
401 Unauthorized	Invalid token	Generate new PAT, update config
Repository not found	Wrong repo path	Use correct absolute path

---

6. Registering MCP Servers

• Add entries as shown above to cline_mcp_settings.json.
• Save the file.
• Restart VSCode or the MCP environment.

Common Errors & Fixes

Error	Cause	Fix
Connection refused	Server misconfig	Check command, args, env
Path errors	Wrong paths	Use absolute, existing paths

---

7. Running & Testing

• Verify servers are running (check MCP interface).
• Run test commands:

# GitHub MCP
list_repositories

# Git MCP
git_status

• Expected outputs: list of repos, git status info.

Common Errors & Fixes

Error	Cause	Fix
Tool not found	Server not running	Check MCP config, restart
Rate limit exceeded	No auth or too many calls	Use PAT, wait for reset

---

8. Troubleshooting

Error	Cause	Fix
Module not found	Missing deps	npm install or pip install
401 Unauthorized	Invalid token	Generate new PAT
Permission denied	File access	Run as admin, fix perms
Build errors	TypeScript issues	Fix code, rebuild
Connection refused	Server misconfig	Check MCP config
Repository not found	Wrong path	Use absolute, existing repo path
Rate limit exceeded	No auth	Use PAT, wait

Diagnostic Commands:

node -v
python --version
git --version

---

9. Common Errors & Fixes (Detailed)

Git MCP Server

Error	Cause	Fix
ModuleNotFoundError	Missing Python packages	Run pip install -r requirements.txt inside git-mcp
Repository not found	Wrong or relative repo path	Use absolute path to an existing Git repo
Permission denied	File access issues	Run terminal as admin, fix folder permissions
Python not found	Wrong interpreter	Verify python --version, use correct venv

---

GitHub MCP Server

Error	Cause	Fix
401 Unauthorized	Invalid or missing GitHub token	Generate new PAT with repo, workflow, read:org scopes, update MCP config
Rate limit exceeded	No auth or too many API calls	Use PAT, wait for reset (~1 hour)
Module not found	Missing Node packages	Run npm install inside github-mcp
Build failed	TypeScript errors	Fix errors, then npm run build
Cannot find module	Wrong build path in MCP config	Check MCP config points to dist/index.js or build/index.js

---

Other MCP Servers

Error	Cause	Fix
Port already in use	Port conflict	Change port in server config or stop other services
Environment variable missing	Misconfigured .env or MCP config	Add required env vars (tokens, keys)
Connection refused	Server not running or misconfigured	Check MCP config, restart server

---

10. Additional Tips

• Use simple language and avoid jargon.
• Include platform-specific notes (Windows paths, Linux permissions).
• Verify each step before proceeding.
• Update the guide as you learn more.
• Contribute fixes or improvements via pull requests.

---

11. Resources

• Node.js
• Python
• Git
• GitHub Tokens
• Model Context Protocol (MCP) (if available)
• VSCode

---

12. Contributing

If you encounter new errors or have suggestions, please open an issue or pull request to improve this guide for everyone.

---

This guide is designed to be a living document.

Update it as the MCP ecosystem evolves!