# Claude TypeScript MCP Servers (For Software Developers)
A comprehensive collection of Model Context Protocol (MCP) servers that
transform Claude Desktop into a powerful development assistant. This project
leverages your flat-rate Claude Pro/Max subscription to provide capabilities
similar to Cline, but without the per-token API costs.
日本語による解説記事:
[Cline任せでコード書いてたらAPIクレジットが爆散したのでClaude Desktop + MCPをいい感じにしてサブスクだけで無双する](https://zenn.dev/ukkz/articles/c8726063edd2cd)
## 🚀 Features
- **File System Operations** - Read, write, and manage files with security
restrictions
- **Git Integration** - Full Git workflow support including commits, branches,
and diffs
- **GitHub API** - Manage repositories, issues, PRs, and more with multi-account
support
- **Web Search** - AI-powered search with Sonar and traditional keyword search
with Brave
- **Browser Automation** - 30+ Puppeteer tools for web scraping and automation
- **Shell Commands** - Execute development commands in a controlled environment
- **URL Fetching** - Extract content from web pages with HTML-to-Markdown
conversion
## 📋 Requirements
- [Node.js](https://nodejs.org/) v18 or higher
- [Bun](https://bun.sh/) runtime
- [Claude Desktop](https://anthropic.com/claude) application
- API keys for external services (Brave Search, Perplexity/Sonar)
## 🛠️ Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/claude-ts-mcps.git
cd claude-ts-mcps
# Install dependencies
bun install
```
## ⚙️ Configuration
Create a configuration file for Claude Desktop with all the MCP servers:
```json
{
"mcpServers": {
"filesystem": {
"command": "/Users/username/.bun/bin/bun",
"args": [
"run",
"/path/to/claude-ts-mcps/src/filesystem.ts",
"/Users/username"
]
},
"git": {
"command": "/Users/username/.bun/bin/bun",
"args": ["run", "/path/to/claude-ts-mcps/src/git.ts"]
},
"github": {
"command": "/Users/username/.bun/bin/bun",
"args": ["run", "/path/to/claude-ts-mcps/src/github.ts"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_DEFAULT_TOKEN",
"GITHUB_TOKEN_WORK": "YOUR_WORK_ACCOUNT_TOKEN",
"GITHUB_TOKEN_PERSONAL": "YOUR_PERSONAL_ACCOUNT_TOKEN"
}
},
"brave-search": {
"command": "/Users/username/.bun/bin/bun",
"args": ["run", "/path/to/claude-ts-mcps/src/brave-search.ts"],
"env": {
"BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
}
},
"sonar": {
"command": "/Users/username/.bun/bin/bun",
"args": ["run", "/path/to/claude-ts-mcps/src/sonar.ts"],
"env": {
"PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY"
}
},
"puppeteer": {
"command": "/Users/username/.bun/bin/bun",
"args": ["run", "/path/to/claude-ts-mcps/src/puppeteer/index.ts"]
},
"shell": {
"command": "/Users/username/.bun/bin/bun",
"args": ["run", "/path/to/claude-ts-mcps/src/shell.ts"]
},
"fetch": {
"command": "/Users/username/.bun/bin/bun",
"args": ["run", "/path/to/claude-ts-mcps/src/fetch.ts"],
"env": {
"CUSTOM_USER_AGENT": "YOUR_CUSTOM_USER_AGENT",
"IGNORE_ROBOTS_TXT": "false"
}
}
}
}
```
## 🔧 Available Tools
### File System Operations (`filesystem`)
- **Security**: Restricted to specified directories with symlink protection
- **Core Operations**:
- Read/write files with encoding support (utf-8, base64, hex)
- Partial file reading by byte range or line range
- Move, copy, delete, append files
- Create directories and manage file trees
- **Advanced Editing**:
- Text replacement with diff preview
- Line-based operations (replace, insert, delete specific lines)
- Regular expression replacements with capture groups
- **Search Capabilities**:
- Search files by name patterns
- Search content within files (plain text or regex)
- Exclude patterns support
- **Batch Operations**:
- Execute multiple file operations efficiently
- Parallel execution for read operations
- Transactional mode with rollback support
- **Archive Management**:
- Compress files (zip, tar, tar.gz)
- Extract archives with overwrite control
- **File Monitoring**:
- Check for file changes since specific time
- Support for change, rename, and delete events
- **Use Cases**: Code editing, project management, file analysis, bulk
operations
### Git Integration (`git`)
- **Full Git Workflow**: init, add, commit, branch, checkout, diff, log
- **Repository Management**: status tracking, history viewing
- **Tag Management**:
- Create lightweight and annotated tags
- List tags with pattern filtering
- Show tag details and messages
- Delete unwanted tags
- **Use Cases**: Version control, code review, project history, release management
### GitHub API (`github`)
- **Repository Management**: Create, search, manage repositories
- **Issues & PRs**: Create, update, merge pull requests and issues
- **Release Management**: Create, update, and manage releases
- **Multi-Account Support**: Switch between work/personal accounts
- **File Operations**: Direct file creation and updates via API
### Web Search Tools
#### AI-Powered Search (`sonar`)
- **Natural Language Understanding**: Ask complex questions in plain language
- **Synthesized Answers**: Get comprehensive responses with citations
- **Multiple Models**:
- `sonar`: Fast general-purpose search
- `sonar-pro`: Complex queries with 200k context
- `sonar-reasoning`: Chain-of-thought reasoning
- `sonar-deep-research`: Comprehensive research mode
- **Use Cases**: Research, fact-checking, learning about complex topics
#### Traditional Search (`brave-search`)
- **Web Search**: Keyword-based search returning multiple results
- **Local Search**: Find businesses and services
- **Use Cases**: Quick lookups, finding multiple sources, local information
### Browser Automation (`puppeteer`)
Our most comprehensive tool with 30+ functions organized into categories:
#### 🧭 Navigation & Basic Interaction
- Navigate to URLs, take screenshots
- Click elements, fill forms, select options
- Hover over elements, execute JavaScript
#### ⏳ Wait Operations
- Wait for elements, timeouts, navigation
- Wait for custom JavaScript conditions
#### ⌨️ Keyboard Operations
- Press keys and key combinations
- Type text with human-like delays
#### 📄 Page Management
- Set viewport size, go back/forward, reload
- Generate PDFs, emulate devices
#### 🍪 Cookies & Authentication
- Set/get cookies, HTTP authentication
#### ℹ️ Information Retrieval
- Get page title, URL, HTML content
- Extract text and detailed element information
#### 🖼️ Frame Operations (Advanced)
- List all frames, switch between frames
- Execute JavaScript in specific frames
- Search elements across all frames
#### 🔧 Miscellaneous
- Add script tags, clear input fields
### Shell Commands (`shell`)
- **Controlled Execution**: Allowlist-based command restrictions
- **Development Tools**: npm, yarn, bun, git, node, python, tsc
- **Security**: Prevents dangerous operations, directory restrictions
- **Features**: Auto-parsing of command strings, output size limits, timeout
control
- **Streaming Mode**: Now enabled by default! Captures output from long-running
processes
- Automatically returns partial output after timeout (default: 10s) or buffer
limit (100KB)
- Normal commands complete as usual; only affects long-running processes
- Processes are automatically terminated after streaming timeout (safe
default)
- Keep processes running with `killOnStreamingTimeout: false`
- Perfect for: development servers, build watchers, interactive commands
- Disable with `streaming: false` if needed
- **Use Cases**: Package management, build processes, script execution, server
monitoring
### URL Content Fetching (`fetch`)
- **Content Extraction**: Convert HTML to clean Markdown
- **Customization**: Custom user agents, robots.txt handling
- **Use Cases**: Documentation reading, content analysis
## 💡 Usage Examples
### Development Workflow
```
You: "Create a new React component for user authentication"
Claude: *Uses filesystem to create component file, npm to install dependencies*
You: "Find examples of OAuth implementation on GitHub"
Claude: *Uses GitHub search and fetch to find and analyze implementations*
You: "Test the login form on our staging site"
Claude: *Uses Puppeteer to navigate, fill forms, and verify functionality*
```
### Research and Analysis
```
You: "What are the latest best practices for Next.js 14 App Router?"
Claude: *Uses Sonar for comprehensive research with citations*
You: "Compare our package.json with similar projects"
Claude: *Uses GitHub to find similar projects, filesystem to read local files*
```
### Automation
```
You: "Extract all product prices from this e-commerce site"
Claude: *Uses Puppeteer to navigate pages, extract data, and compile results*
You: "Monitor our GitHub issues and create a summary"
Claude: *Uses GitHub API to fetch issues, analyze patterns, generate report*
```
## 🔒 Security Considerations
- **File System**: Restricted to specified directories only
- **Shell**: Commands must be in the allowlist
- **Credentials**: Store API keys securely, use environment variables
- **GitHub**: Use minimal token permissions
- **Fetch**: Respects robots.txt by default
## 🏗️ Project Structure
```
claude-ts-mcps/
├── src/
│ ├── filesystem.ts # File operations
│ ├── git.ts # Git integration
│ ├── github.ts # GitHub API (main entry)
│ ├── github/ # GitHub implementation
│ ├── brave-search.ts # Brave search API
│ ├── sonar.ts # Perplexity Sonar API
│ ├── sonar/ # Sonar types and utilities
│ ├── puppeteer/ # Browser automation
│ │ ├── index.ts # Main entry point
│ │ ├── tools/ # Tool definitions
│ │ ├── handlers/ # Implementation
│ │ └── state.ts # State management
│ ├── shell.ts # Shell commands (entry)
│ ├── shell/ # Shell implementation
│ │ ├── index.ts # Main logic
│ │ ├── executor.ts # Command execution
│ │ ├── types.ts # Type definitions
│ │ └── ... # Other modules
│ └── fetch.ts # URL fetching
└── package.json
```
## 🚧 Development
To add new functionality:
1. Create a new TypeScript file in `src/`
2. Implement the MCP server using `@modelcontextprotocol/sdk`
3. Add tool definitions with clear descriptions
4. Include proper error handling and validation
5. Update the configuration file
### Testing Your Changes
```bash
# Run a specific MCP server directly
bun run src/your-new-server.ts
# Test with Claude Desktop
# Update your config and restart Claude
```
### Type Checking
This project uses TypeScript for type safety. Several type checking commands are
available:
```bash
# Standard type check (all strict checks enabled)
bun run type-check
# Type check with file watching for development
bun run type-check:watch
# Type check without unused variable warnings (good for development)
bun run check:loose
# Strict type check (same as type-check)
bun run check:strict
```
#### Current Type Issues
The project is functional but has some type issues that are being addressed:
- Some Puppeteer APIs need proper type imports
- A few cases of potential undefined values need guards
- Unused variables in some files (can be ignored during development)
These don't affect runtime functionality but will be cleaned up over time.
### Code Formatting
This project uses Prettier for consistent code formatting. The following
commands are available:
```bash
# Format all files
bun run format
# Check formatting without making changes
bun run format:check
# Format only source files (src directory)
bun run format:src
# Check formatting of source files only
bun run format:check:src
# Run both formatting check and type check
bun run lint
# Fix formatting and run type check
bun run lint:fix
```
#### Prettier Configuration
The project uses the following Prettier settings (`.prettierrc`):
- **Print Width**: 100 characters (80 for JSON/Markdown)
- **Tab Width**: 2 spaces
- **Semicolons**: Always
- **Quotes**: Double quotes
- **Trailing Commas**: All (ES5+)
- **Arrow Parens**: Always include parentheses
#### Formatting on Save
For the best development experience, configure your editor to format on save:
**VS Code**: Add to `.vscode/settings.json`:
```json
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
```
**Other Editors**: Check your editor's documentation for Prettier integration.
## 📚 Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [MCP SDK Reference](https://modelcontextprotocol.io/sdks)
- [Anthropic Claude](https://www.anthropic.com/claude)
- [Brave Search API](https://api.search.brave.com/app/documentation)
- [Perplexity API](https://docs.perplexity.ai/)
## 📄 License
[MIT License](LICENSE)