README.md•4.63 kB
# MCP Scratchpad Server
[](https://pypi.org/project/mcp-server-scratchpad/)
[](https://opensource.org/licenses/MIT)
An MCP (Model Context Protocol) server that provides a "think" tool for structured reasoning, based on the [Anthropic blog post](https://www.anthropic.com/engineering/claude-think-tool).
## Overview
The Scratchpad MCP server allows Claude and other LLMs to add dedicated thinking steps during complex tool use scenarios. This improves problem-solving by creating space for structured reasoning and helps the model carefully process tool call outputs.
## Features
- **Think Tool**: Add thoughts to a timestamped log for structured reasoning
- **Thoughts Log Resource**: View all logged thoughts in JSON format
- **Clear Tool**: Reset the thinking log when needed
- **Structured Thinking Prompt**: Template for systematic problem-solving
## Installation
### Quick Start (Recommended)
Run directly with uvx (no installation needed):
```bash
uvx mcp-server-scratchpad
```
### PyPI Installation
Install globally with pip or uv:
```bash
# Using pip
pip install mcp-server-scratchpad
# Using uv
uv pip install mcp-server-scratchpad
```
### Development Installation
For local development:
```bash
# Clone the repository
git clone https://github.com/JoshuaOliphant/scratchpad_mcp.git
cd scratchpad_mcp
# Install dependencies
uv sync
# Run the server
uv run mcp-server-scratchpad
```
## Usage
### With Claude Desktop
Add to your Claude Desktop configuration:
On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
Using uvx:
```json
{
"mcpServers": {
"scratchpad": {
"command": "uvx",
"args": ["mcp-server-scratchpad"]
}
}
}
```
Using pip installation:
```json
{
"mcpServers": {
"scratchpad": {
"command": "mcp-server-scratchpad"
}
}
}
```
### Testing with MCP Inspector
For development and testing:
```bash
# Using uvx
uvx mcp-server-scratchpad
# Using MCP Inspector (if developing locally)
uv run mcp dev src/mcp_server_scratchpad/server.py
```
## Tools
### think
Add a thinking step to the log.
**Parameters:**
- `thought` (string): The thought to log
**Example:**
```json
{
"thought": "I need to break this problem into smaller parts..."
}
```
### clear_thoughts
Clear all thoughts from the log.
**No parameters required**
## Resources
### log://thoughts
Returns all logged thoughts as a JSON array with timestamps.
**Example output:**
```json
[
{
"timestamp": "2024-01-20T10:30:45.123456",
"thought": "First, I need to understand the requirements..."
},
{
"timestamp": "2024-01-20T10:31:02.789012",
"thought": "The main components are X, Y, and Z..."
}
]
```
## Prompts
### Structured Thinking
A template for systematic problem-solving using the think tool.
**Parameters:**
- `topic` (string): The topic or problem to think through
## Use Cases
The scratchpad tool is particularly useful for:
1. **Long chains of tool calls**: Keep track of intermediate results and reasoning
2. **Complex problem-solving**: Break down problems systematically
3. **Policy-heavy environments**: Verify compliance with guidelines
4. **Sequential decision making**: Document the reasoning process
5. **Edge case handling**: Think through unusual scenarios
## Example Workflow
1. Start with a complex problem
2. Use the "Structured Thinking" prompt to set up the approach
3. Use the `think` tool multiple times to log reasoning steps
4. Check progress with the `log://thoughts` resource
5. Clear the log when starting a new problem
## Best Practices
- Use descriptive thoughts that explain the "why" not just the "what"
- Break complex problems into smaller, manageable parts
- Validate reasoning at each step
- Summarize conclusions at the end
- Clear the log between unrelated tasks
## Development
To modify the server:
1. Fork the repository
2. Make your changes to `src/mcp_server_scratchpad/server.py`
3. Test with `uv run mcp dev src/mcp_server_scratchpad/server.py`
4. Submit a pull request
## Future Enhancements
Potential improvements:
- Persist thoughts to a file
- Add search/filter capabilities
- Support for thought categories or tags
- Export thoughts in different formats
- Integration with other reasoning tools
## License
MIT License - see LICENSE file for details
## Credits
Based on the thinking tool concept from [Anthropic's blog post](https://www.anthropic.com/engineering/claude-think-tool)